Skip to content

Commit bb56c71

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 bb56c71

File tree

1 file changed

+40
-37
lines changed

1 file changed

+40
-37
lines changed

spec/Section 3 -- Type System.md

Lines changed: 40 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,13 @@ 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 a most appropriate serialized primitive for each given scalar type,
383+
and the server should produce each primitive where appropriate.
384+
385+
See [Serialization Format](#sec-Serialization-Format) for more detailed
386+
information on the serialization of scalars in common JSON and other formats.
387+
379388
**Input Coercion**
380389

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

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-
403406

404407
### Int
405408

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

410413
**Result Coercion**
411414

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

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

445448
**Result Coercion**
446449

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

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

472475
**Result Coercion**
473476

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

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

494497
**Result Coercion**
495498

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

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

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

510513
The ID scalar type represents a unique identifier, often used to refetch an
511514
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`.
515+
a {String}; however, it is not intended to be human-readable. While it is
516+
often numeric, it should always serialize as a {String}.
514517

515518
**Result Coercion**
516519

@@ -583,8 +586,8 @@ type Person {
583586
}
584587
```
585588

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
589+
Where `name` is a field that will yield a {String} value, and `age` is a field
590+
that will yield an {Int} value, and `picture` is a field that will yield a
588591
`Url` value.
589592

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

0 commit comments

Comments
 (0)