@@ -390,29 +390,31 @@ the result with a RFC 4122 compliant parser. Another example of a potentially
390390useful custom scalar is ` URL ` , which serializes as a string, but is guaranteed
391391by the server to be a valid URL.
392392
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.
400402
401403``` graphql example
402404scalar UUID @specifiedBy (url : " https://tools.ietf.org/html/rfc4122" )
403405scalar URL @specifiedBy (url : " https://tools.ietf.org/html/rfc3986" )
404406```
405407
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 .
409411
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
411413would likely disrupt tooling or could introduce breaking changes within the
412414linked specification 's contents .
413415
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 .
416418
417419Note : Custom scalars should also summarize the specified format and provide
418420examples in their description .
@@ -2058,7 +2060,7 @@ directive @specifiedBy(url: String!) on SCALAR
20582060```
20592061
20602062The `@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
20622064[custom scalar types ](#sec-Scalars.Custom-Scalars). The URL should point to a
20632065human-readable specification of the data format, serialization, and
20642066coercion rules. It must not appear on built-in scalar types.
0 commit comments