@@ -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,13 @@ 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 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
+
379
388
** Input Coercion**
380
389
381
390
If a GraphQL server expects a scalar type as input to an argument, coercion
@@ -394,12 +403,6 @@ input value.
394
403
For all types below, with the exception of Non-Null, if the explicit value
395
404
{null} is provided, then the result of input coercion is {null}.
396
405
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
406
404
407
### Int
405
408
@@ -409,7 +412,7 @@ that type to represent this scalar.
409
412
410
413
** Result Coercion**
411
414
412
- Fields returning the type ` Int ` expect to encounter 32-bit integer
415
+ Fields returning the type { Int} expect to encounter 32-bit integer
413
416
internal values.
414
417
415
418
GraphQL servers may coerce non-integer internal values to integers when
@@ -444,10 +447,10 @@ should use that type to represent this scalar.
444
447
445
448
** Result Coercion**
446
449
447
- Fields returning the type ` Float ` expect to encounter double-precision
450
+ Fields returning the type { Float} expect to encounter double-precision
448
451
floating-point internal values.
449
452
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
451
454
reasonable without losing information, otherwise they must raise a field error.
452
455
Examples of this may include returning ` 1.0 ` for the integer number ` 1 ` , or
453
456
` 123.0 ` for the string ` "123" ` .
@@ -471,9 +474,9 @@ and that representation must be used here.
471
474
472
475
** Result Coercion**
473
476
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.
475
478
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
477
480
without losing information, otherwise they must raise a field error. Examples of
478
481
this may include returning the string ` "true" ` for a boolean true value, or the
479
482
string ` "1" ` for the integer ` 1 ` .
@@ -493,9 +496,9 @@ representation of the integers `1` and `0`.
493
496
494
497
** Result Coercion**
495
498
496
- Fields returning the type ` Boolean ` expect to encounter boolean internal values.
499
+ Fields returning the type { Boolean} expect to encounter boolean internal values.
497
500
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
499
502
without losing information, otherwise they must raise a field error. Examples of
500
503
this may include returning ` true ` for non-zero numbers.
501
504
@@ -509,8 +512,8 @@ other input values must raise a query error indicating an incorrect type.
509
512
510
513
The ID scalar type represents a unique identifier, often used to refetch an
511
514
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} .
514
517
515
518
** Result Coercion**
516
519
@@ -583,8 +586,8 @@ type Person {
583
586
}
584
587
```
585
588
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
588
591
`Url ` value .
589
592
590
593
A query of an object value must select at least one field . This selection of
0 commit comments