Skip to content

Commit a23eb61

Browse files
committed
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
1 parent 40d025c commit a23eb61

File tree

2 files changed

+20
-18
lines changed

2 files changed

+20
-18
lines changed

spec/Section 3 -- Type System.md

+16-14
Original file line numberDiff line numberDiff line change
@@ -390,29 +390,31 @@ the result with a RFC 4122 compliant parser. Another example of a potentially
390390
useful custom scalar is `URL`, which serializes as a string, but is guaranteed
391391
by 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
402404
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
403405
scalar 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
411413
would likely disrupt tooling or could introduce breaking changes within the
412414
linked 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

417419
Note: Custom scalars should also summarize the specified format and provide
418420
examples in their description.
@@ -2058,7 +2060,7 @@ directive @specifiedBy(url: String!) on SCALAR
20582060
```
20592061

20602062
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
20622064
[custom scalar types](#sec-Scalars.Custom-Scalars). The URL should point to a
20632065
human-readable specification of the data format, serialization, and
20642066
coercion rules. It must not appear on built-in scalar types.

spec/Section 4 -- Introspection.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -243,16 +243,16 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration.
243243

244244
Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields.
245245

246-
Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide
247-
`specifiedByURL` as a scalar specification URL.
246+
Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide
247+
`specifiedByURL` as a *scalar specification URL*.
248248

249249
Fields
250250

251251
* `kind` must return `__TypeKind.SCALAR`.
252252
* `name` must return a String.
253-
* `specifiedByURL` may return a String (in the form of a URL) for custom scalars,
254-
otherwise must be {null}.
255253
* `description` may return a String or {null}.
254+
* `specifiedByURL` may return a String (in the form of a URL) for custom
255+
scalars, otherwise must be {null}.
256256
* All other fields must return {null}.
257257

258258

0 commit comments

Comments
 (0)