Skip to content

Commit

Permalink
Editorial: Define 'Schema Specification URL' (#856)
Browse files Browse the repository at this point in the history
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
  • Loading branch information
leebyron authored Apr 16, 2021
1 parent 40d025c commit 086bb1f
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 18 deletions.
30 changes: 16 additions & 14 deletions spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions spec/Section 4 -- Introspection.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}.


Expand Down

0 comments on commit 086bb1f

Please sign in to comment.