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

Add links to contributed custom scalar specs at scalars.graphql.org #1009

Merged
merged 7 commits into from
Feb 11, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,12 +405,17 @@ 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")
scalar DateTime
@specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")
```

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.

Note: Some community-maintained custom scalar specifications are hosted at
[scalars.graphql.org](https://scalars.graphql.org/).

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.
Expand All @@ -419,7 +424,9 @@ 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.
examples in their description; see the GraphQL scalars
[implementation guide](https://scalars.graphql.org/implementation-guide) for
more guidance.

**Result Coercion and Serialization**

Expand Down Expand Up @@ -2110,6 +2117,9 @@ 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.

Note: Details on implementing a GraphQL scalar specification can be found in the
[scalars.graphql.org implementation guide](https://scalars.graphql.org/implementation-guide).

In this example, a custom scalar type for `UUID` is defined with a URL pointing
to the relevant IETF specification.

Expand Down