From a23eb61eef8020d6f8c9a89a6681e55dbf201ab2 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 16 Apr 2021 15:10:57 -0700 Subject: [PATCH] Editorial: Define 'Schema Specification URL' One last follow up to #649 RFC, this uses the new term definition syntax and ensures the term usage is consistent throughout the document. Also makes a minor editorial change in the introspection section to list the `description` field under `name` like the other sections --- spec/Section 3 -- Type System.md | 30 ++++++++++++++++-------------- spec/Section 4 -- Introspection.md | 8 ++++---- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index f279a2af7..cc7607a8a 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -390,29 +390,31 @@ the result with a RFC 4122 compliant parser. Another example of a potentially useful custom scalar is `URL`, which serializes as a string, but is guaranteed by the server to be a valid URL. -When defining a custom scalar, GraphQL services should provide a specification -URL via the `@specifiedBy` directive or the `specifiedByURL` introspection field. -This URL must link to a human-readable specification of the data format, -serialization, and coercion rules for the scalar. For example, a GraphQL service -providing a `UUID` scalar may link to RFC 4122, or some custom document defining -a reasonable subset of that RFC. If a scalar specification URL is present, -systems and tools that are aware of it should conform to its described rules. +:: When defining a custom scalar, GraphQL services should provide a *scalar +specification URL* via the `@specifiedBy` directive or the `specifiedByURL` +introspection field. This URL must link to a human-readable specification of the +data format, serialization, and coercion rules for the scalar. + +For example, a GraphQL service providing a `UUID` scalar may link to RFC 4122, +or some custom document defining a reasonable subset of that RFC. If a *scalar +specification URL* is present, systems and tools that are aware of it should +conform to its described rules. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986") ``` -Custom scalar specifications should provide a single, stable format to avoid -ambiguity. If the linked specification is in flux, the service should link to a -fixed version rather than to a resource which might change. +Custom *scalar specification URL*s should provide a single, stable format to +avoid ambiguity. If the linked specification is in flux, the service should link +to a fixed version rather than to a resource which might change. -Custom scalar specification URLs should not be changed once defined. Doing so +Custom *scalar specification URL*s should not be changed once defined. Doing so would likely disrupt tooling or could introduce breaking changes within the linked specification's contents. -Built-in scalar types must not provide a specification URL as they are specified -by this document. +Built-in scalar types must not provide a *scalar specification URL* as they are +specified by this document. Note: Custom scalars should also summarize the specified format and provide examples in their description. @@ -2058,7 +2060,7 @@ directive @specifiedBy(url: String!) on SCALAR ``` The `@specifiedBy` directive is used within the type system definition language -to provide a URL for specifying the behavior of +to provide a *scalar specification URL* for specifying the behavior of [custom scalar types](#sec-Scalars.Custom-Scalars). The URL should point to a human-readable specification of the data format, serialization, and coercion rules. It must not appear on built-in scalar types. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 4f9a7317a..2c80a18f4 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -243,16 +243,16 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide -`specifiedByURL` as a scalar specification URL. +Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide +`specifiedByURL` as a *scalar specification URL*. Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specifiedByURL` may return a String (in the form of a URL) for custom scalars, - otherwise must be {null}. * `description` may return a String or {null}. +* `specifiedByURL` may return a String (in the form of a URL) for custom + scalars, otherwise must be {null}. * All other fields must return {null}.