Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editorial: Define 'Schema Specification URL' #856

Merged
merged 1 commit into from Apr 16, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 16 additions & 14 deletions spec/Section 3 -- Type System.md
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
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