@@ -390,29 +390,31 @@ the result with a RFC 4122 compliant parser. Another example of a potentially
390
390
useful custom scalar is ` URL ` , which serializes as a string, but is guaranteed
391
391
by the server to be a valid URL.
392
392
393
- When defining a custom scalar, GraphQL services should provide a specification
394
- URL via the ` @specifiedBy ` directive or the ` specifiedByURL ` introspection field.
395
- This URL must link to a human-readable specification of the data format,
396
- serialization, and coercion rules for the scalar. For example, a GraphQL service
397
- providing a ` UUID ` scalar may link to RFC 4122, or some custom document defining
398
- a reasonable subset of that RFC. If a scalar specification URL is present,
399
- systems and tools that are aware of it should conform to its described rules.
393
+ :: When defining a custom scalar, GraphQL services should provide a * scalar
394
+ specification URL* via the ` @specifiedBy ` directive or the ` specifiedByURL `
395
+ introspection field. This URL must link to a human-readable specification of the
396
+ data format, serialization, and coercion rules for the scalar.
397
+
398
+ For example, a GraphQL service providing a ` UUID ` scalar may link to RFC 4122,
399
+ or some custom document defining a reasonable subset of that RFC. If a * scalar
400
+ specification URL* is present, systems and tools that are aware of it should
401
+ conform to its described rules.
400
402
401
403
``` graphql example
402
404
scalar UUID @specifiedBy (url : " https://tools.ietf.org/html/rfc4122" )
403
405
scalar URL @specifiedBy (url : " https://tools.ietf.org/html/rfc3986" )
404
406
```
405
407
406
- Custom scalar specifications should provide a single , stable format to avoid
407
- ambiguity . If the linked specification is in flux , the service should link to a
408
- fixed version rather than to a resource which might change .
408
+ Custom * scalar specification URL * s should provide a single , stable format to
409
+ avoid ambiguity . If the linked specification is in flux , the service should link
410
+ to a fixed version rather than to a resource which might change .
409
411
410
- Custom scalar specification URLs should not be changed once defined . Doing so
412
+ Custom * scalar specification URL * s should not be changed once defined . Doing so
411
413
would likely disrupt tooling or could introduce breaking changes within the
412
414
linked specification 's contents .
413
415
414
- Built -in scalar types must not provide a specification URL as they are specified
415
- by this document .
416
+ Built -in scalar types must not provide a * scalar specification URL * as they are
417
+ specified by this document .
416
418
417
419
Note : Custom scalars should also summarize the specified format and provide
418
420
examples in their description .
@@ -2058,7 +2060,7 @@ directive @specifiedBy(url: String!) on SCALAR
2058
2060
```
2059
2061
2060
2062
The `@specifiedBy ` directive is used within the type system definition language
2061
- to provide a URL for specifying the behavior of
2063
+ to provide a * scalar specification URL * for specifying the behavior of
2062
2064
[custom scalar types ](#sec-Scalars.Custom-Scalars). The URL should point to a
2063
2065
human-readable specification of the data format, serialization, and
2064
2066
coercion rules. It must not appear on built-in scalar types.
0 commit comments