Skip to content

Commit d8ed061

Browse files
committed
Use UUID as a less controversial example
Also fix a few more URI->URL references.
1 parent 09a8f8b commit d8ed061

File tree

2 files changed

+16
-17
lines changed

2 files changed

+16
-17
lines changed

spec/Section 3 -- Type System.md

+15-16
Original file line numberDiff line numberDiff line change
@@ -344,16 +344,15 @@ custom scalar is `Url`, which serializes as a string, but is guaranteed by
344344
the server to be a valid URL.
345345

346346
When defining an additional scalar, GraphQL systems should use the `@specified`
347-
directive to provide a URL pointing to a human-readable
348-
specification of the data format, serialization, and coercion rules for the
349-
scalar. For example, a GraphQL system providing a `Date` or `DateTime` scalar
350-
might link to RFC 3339, or some document defining a reasonable subset of that
351-
RFC. If a specification URI is present, systems must conform to the described
352-
rules. Built-in scalar types should not provide a URI.
347+
directive to provide a URL pointing to a human-readable specification of the
348+
data format, serialization, and coercion rules for the scalar. For example, a
349+
GraphQL system providing a `UUID` scalar might link to RFC 4122, or some
350+
document defining a reasonable subset of that RFC. If a specification URL is
351+
present, systems must conform to the described rules. Built-in scalar types
352+
should not provide a URL.
353353

354354
```graphql example
355-
scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339")
356-
scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986")
355+
scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122")
357356
```
358357

359358
A server may omit any of the built-in scalars from its schema, for example if a
@@ -1802,24 +1801,24 @@ directive @specified(
18021801

18031802
The `@specified` directive is used within the type system definition language
18041803
to provide a URL for specifying the behaviour of custom
1805-
scalar definitions. The URI should point to a human-readable specification of
1804+
scalar definitions. The URL should point to a human-readable specification of
18061805
the data format, serialization, and coercion rules for the scalar. For example,
1807-
a GraphQL system providing a `Date` or `DateTime` scalar might link to RFC 3339,
1806+
a GraphQL system providing a `UUID` scalar might link to RFC 4122,
18081807
or some document defining a reasonable subset of that RFC. If a specification
1809-
URI is present, systems must conform to the described rules. Built-in scalar
1810-
types should not provide a URI in this way.
1808+
URL is present, systems must conform to the described rules. Built-in scalar
1809+
types should not provide a URL in this way.
18111810

18121811
Specifications linked in this way should provide a single, stable scalar format
18131812
to avoid ambiguity. This means that if the specification is in flux, the system
18141813
should link to a fixed version rather than to a resource whose contents might
1815-
change. It is also recommended that the URI associated with a scalar not be
1814+
change. It is also recommended that the URL associated with a scalar not be
18161815
changed once defined; doing so is likely to disrupt tooling, and may come with
18171816
changes to the specification contents which are themselves breaking.
18181817

1819-
In this example, two custom scalar types are defined with URIs pointing to the
1818+
In this example, two custom scalar types are defined with URLs pointing to the
18201819
relevant IETF specifications.
18211820

18221821
```graphql example
1823-
scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339")
1824-
scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986")
1822+
scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122")
1823+
scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986")
18251824
```

spec/Section 4 -- Introspection.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration.
236236
Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields.
237237

238238
A GraphQL type designer should use the `@specified` directive to provide
239-
a specification URI describing the data format, serialization, and coercion
239+
a specification URL describing the data format, serialization, and coercion
240240
rules for the scalar. It is recommended to also summarize the format and provide
241241
an example in the description field.
242242

0 commit comments

Comments
 (0)