@@ -327,18 +327,14 @@ represent additional fields a GraphQL client only accesses locally.
327
327
ScalarTypeDefinition : Description? scalar Name Directives[ Const] ?
328
328
329
329
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
331
331
GraphQL scalars.
332
332
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
342
338
client-specific primitive for time. Another example of a potentially useful
343
339
custom scalar is ` Url ` , which serializes as a string, but is guaranteed by
344
340
the server to be a valid URL.
@@ -348,25 +344,31 @@ scalar Time
348
344
scalar Url
349
345
```
350
346
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.
358
360
359
361
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.
361
363
362
- ** Result Coercion**
364
+ ** Result Coercion and Serialization **
363
365
364
366
A GraphQL server, when preparing a field of a given scalar type, must uphold the
365
367
contract the scalar type describes, either by coercing the value or producing a
366
368
field error if a value cannot be coerced or if coercion may result in data loss.
367
369
368
370
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
370
372
` true ` value may produce ` 1 ` or a string value ` "123" ` may be parsed as base-10
371
373
` 123 ` . However if internal type coercion cannot be reasonably performed without
372
374
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
376
378
requirement is that the server must yield values which adhere to the expected
377
379
Scalar type.
378
380
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
+
379
385
** Input Coercion**
380
386
381
387
If a GraphQL server expects a scalar type as input to an argument, coercion
@@ -394,12 +400,6 @@ input value.
394
400
For all types below, with the exception of Non-Null, if the explicit value
395
401
{null} is provided, then the result of input coercion is {null}.
396
402
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
-
403
403
404
404
### Int
405
405
@@ -409,7 +409,7 @@ that type to represent this scalar.
409
409
410
410
** Result Coercion**
411
411
412
- Fields returning the type ` Int ` expect to encounter 32-bit integer
412
+ Fields returning the type { Int} expect to encounter 32-bit integer
413
413
internal values.
414
414
415
415
GraphQL servers may coerce non-integer internal values to integers when
@@ -444,10 +444,10 @@ should use that type to represent this scalar.
444
444
445
445
** Result Coercion**
446
446
447
- Fields returning the type ` Float ` expect to encounter double-precision
447
+ Fields returning the type { Float} expect to encounter double-precision
448
448
floating-point internal values.
449
449
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
451
451
reasonable without losing information, otherwise they must raise a field error.
452
452
Examples of this may include returning ` 1.0 ` for the integer number ` 1 ` , or
453
453
` 123.0 ` for the string ` "123" ` .
@@ -471,9 +471,9 @@ and that representation must be used here.
471
471
472
472
** Result Coercion**
473
473
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.
475
475
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
477
477
without losing information, otherwise they must raise a field error. Examples of
478
478
this may include returning the string ` "true" ` for a boolean true value, or the
479
479
string ` "1" ` for the integer ` 1 ` .
@@ -493,9 +493,9 @@ representation of the integers `1` and `0`.
493
493
494
494
** Result Coercion**
495
495
496
- Fields returning the type ` Boolean ` expect to encounter boolean internal values.
496
+ Fields returning the type { Boolean} expect to encounter boolean internal values.
497
497
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
499
499
without losing information, otherwise they must raise a field error. Examples of
500
500
this may include returning ` true ` for non-zero numbers.
501
501
@@ -509,8 +509,8 @@ other input values must raise a query error indicating an incorrect type.
509
509
510
510
The ID scalar type represents a unique identifier, often used to refetch an
511
511
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} .
514
514
515
515
** Result Coercion**
516
516
@@ -583,8 +583,8 @@ type Person {
583
583
}
584
584
```
585
585
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
588
588
`Url ` value .
589
589
590
590
A query of an object value must select at least one field . This selection of
0 commit comments