Skip to content

Commit 621490b

Browse files
committed
Improve clarity of scalar types
Attempts a more holistic fix to #535 which unifies language around built-in scalars and serialization, shortening the intro to this section in the process.
1 parent a3087c2 commit 621490b

File tree

1 file changed

+37
-37
lines changed

1 file changed

+37
-37
lines changed

spec/Section 3 -- Type System.md

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -327,18 +327,14 @@ represent additional fields a GraphQL client only accesses locally.
327327
ScalarTypeDefinition : Description? scalar Name Directives[Const]?
328328

329329
Scalar types represent primitive leaf values in a GraphQL type system. GraphQL
330-
responses take the form of a hierarchical tree; the leaves on these trees are
330+
responses take the form of a hierarchical tree; the leaves of this tree are
331331
GraphQL scalars.
332332

333-
All GraphQL scalars are representable as strings, though depending on the
334-
response format being used, there may be a more appropriate primitive for the
335-
given scalar type, and server should use those types when appropriate.
336-
337-
GraphQL provides a number of built-in scalars, but type systems can add
338-
additional scalars with semantic meaning. For example, a GraphQL system could
339-
define a scalar called `Time` which, while serialized as a string, promises to
340-
conform to ISO-8601. When querying a field of type `Time`, you can then rely on
341-
the ability to parse the result with an ISO-8601 parser and use a
333+
GraphQL provides a number of built-in scalars (see below), but type systems can
334+
add additional scalars with semantic meaning. For example, a GraphQL system
335+
could define a scalar called `Time` which, while serialized as a string,
336+
promises to conform to ISO-8601. When querying a field of type `Time`, you can
337+
then rely on the ability to parse the result with an ISO-8601 parser and use a
342338
client-specific primitive for time. Another example of a potentially useful
343339
custom scalar is `Url`, which serializes as a string, but is guaranteed by
344340
the server to be a valid URL.
@@ -348,25 +344,31 @@ scalar Time
348344
scalar Url
349345
```
350346

351-
A server may omit any of the built-in scalars from its schema, for example if a
352-
schema does not refer to a floating-point number, then it may omit the
353-
`Float` type. However, if a schema includes a type with the name of one of the
354-
types described here, it must adhere to the behavior described. As an example,
355-
a server must not include a type called `Int` and use it to represent
356-
128-bit numbers, internationalization information, or anything other than what
357-
is defined in this document.
347+
**Built-in Scalars**
348+
349+
GraphQL provides a basic set of well-defined Scalar types: {Int}, {Float},
350+
{String}, {Boolean}, and {ID}. A GraphQL server framework should support all of
351+
these types, and a GraphQL server which provides a type by these names must
352+
adhere to the behavior described below. As an example, a server must not include
353+
a type called {Int} and use it to represent 64-bit numbers, internationalization
354+
information, or anything other than what is defined in this document.
355+
356+
When returning the set of types from the `__Schema` introspection type, all
357+
referenced built-in scalars must be included. If a built-in scalar type is not
358+
referenced anywhere in a schema (there is no field, argument, or input field of
359+
that type) then it must not be included in the schema.
358360

359361
When representing a GraphQL schema using the type system definition language,
360-
the built-in scalar types should be omitted for brevity.
362+
all built-in scalars must be omitted for brevity.
361363

362-
**Result Coercion**
364+
**Result Coercion and Serialization**
363365

364366
A GraphQL server, when preparing a field of a given scalar type, must uphold the
365367
contract the scalar type describes, either by coercing the value or producing a
366368
field error if a value cannot be coerced or if coercion may result in data loss.
367369

368370
A GraphQL service may decide to allow coercing different internal types to the
369-
expected return type. For example when coercing a field of type `Int` a boolean
371+
expected return type. For example when coercing a field of type {Int} a boolean
370372
`true` value may produce `1` or a string value `"123"` may be parsed as base-10
371373
`123`. However if internal type coercion cannot be reasonably performed without
372374
losing information, then it must raise a field error.
@@ -376,6 +378,10 @@ the precise rules of coercion are left to the implementation. The only
376378
requirement is that the server must yield values which adhere to the expected
377379
Scalar type.
378380

381+
GraphQL scalars are serialized according to the serialization format being used.
382+
There may be an appropriate serialized primitive for each given scalar type, and
383+
the server should produce those serialized primitives when appropriate.
384+
379385
**Input Coercion**
380386

381387
If a GraphQL server expects a scalar type as input to an argument, coercion
@@ -394,12 +400,6 @@ input value.
394400
For all types below, with the exception of Non-Null, if the explicit value
395401
{null} is provided, then the result of input coercion is {null}.
396402

397-
**Built-in Scalars**
398-
399-
GraphQL provides a basic set of well-defined Scalar types. A GraphQL server
400-
should support all of these types, and a GraphQL server which provide a type by
401-
these names must adhere to the behavior described below.
402-
403403

404404
### Int
405405

@@ -409,7 +409,7 @@ that type to represent this scalar.
409409

410410
**Result Coercion**
411411

412-
Fields returning the type `Int` expect to encounter 32-bit integer
412+
Fields returning the type {Int} expect to encounter 32-bit integer
413413
internal values.
414414

415415
GraphQL servers may coerce non-integer internal values to integers when
@@ -444,10 +444,10 @@ should use that type to represent this scalar.
444444

445445
**Result Coercion**
446446

447-
Fields returning the type `Float` expect to encounter double-precision
447+
Fields returning the type {Float} expect to encounter double-precision
448448
floating-point internal values.
449449

450-
GraphQL servers may coerce non-floating-point internal values to `Float` when
450+
GraphQL servers may coerce non-floating-point internal values to {Float} when
451451
reasonable without losing information, otherwise they must raise a field error.
452452
Examples of this may include returning `1.0` for the integer number `1`, or
453453
`123.0` for the string `"123"`.
@@ -471,9 +471,9 @@ and that representation must be used here.
471471

472472
**Result Coercion**
473473

474-
Fields returning the type `String` expect to encounter UTF-8 string internal values.
474+
Fields returning the type {String} expect to encounter UTF-8 string internal values.
475475

476-
GraphQL servers may coerce non-string raw values to `String` when reasonable
476+
GraphQL servers may coerce non-string raw values to {String} when reasonable
477477
without losing information, otherwise they must raise a field error. Examples of
478478
this may include returning the string `"true"` for a boolean true value, or the
479479
string `"1"` for the integer `1`.
@@ -493,9 +493,9 @@ representation of the integers `1` and `0`.
493493

494494
**Result Coercion**
495495

496-
Fields returning the type `Boolean` expect to encounter boolean internal values.
496+
Fields returning the type {Boolean} expect to encounter boolean internal values.
497497

498-
GraphQL servers may coerce non-boolean raw values to `Boolean` when reasonable
498+
GraphQL servers may coerce non-boolean raw values to {Boolean} when reasonable
499499
without losing information, otherwise they must raise a field error. Examples of
500500
this may include returning `true` for non-zero numbers.
501501

@@ -509,8 +509,8 @@ other input values must raise a query error indicating an incorrect type.
509509

510510
The ID scalar type represents a unique identifier, often used to refetch an
511511
object or as the key for a cache. The ID type is serialized in the same way as
512-
a `String`; however, it is not intended to be human-readable. While it is
513-
often numeric, it should always serialize as a `String`.
512+
a {String}; however, it is not intended to be human-readable. While it is
513+
often numeric, it should always serialize as a {String}.
514514

515515
**Result Coercion**
516516

@@ -583,8 +583,8 @@ type Person {
583583
}
584584
```
585585

586-
Where `name` is a field that will yield a `String` value, and `age` is a field
587-
that will yield an `Int` value, and `picture` is a field that will yield a
586+
Where `name` is a field that will yield a {String} value, and `age` is a field
587+
that will yield an {Int} value, and `picture` is a field that will yield a
588588
`Url` value.
589589

590590
A query of an object value must select at least one field. This selection of

0 commit comments

Comments
 (0)