From e218d63c83f5a82925037096ccedb419c2667773 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Mon, 16 Jan 2023 10:01:24 +1100 Subject: [PATCH 1/7] Add links to contributed custom scalar specs at scalars.graphql.org --- spec/Section 3 -- Type System.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 7c116bf81..79ae7443a 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -395,7 +395,7 @@ valid URL. :: 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. +data format, serialization, and coercion rules for the scalar. See more on the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). 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 @@ -405,11 +405,12 @@ 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. +to a fixed version rather than to a resource which might change. You can host your custom scalar specification on the GraphQL Foundation owned domain [scalars.graphql.org](https://scalars.graphql.org/), see how to add your specification on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). Custom *scalar specification URL*s should not be changed once defined. Doing so would likely disrupt tooling or could introduce breaking changes within the @@ -419,7 +420,7 @@ 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) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). **Result Coercion and Serialization** @@ -2108,11 +2109,15 @@ The `@specifiedBy` _built-in directive_ is used within the type system definition language 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. +coercion rules. See more on the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). This directive must not appear on built-in scalar types. + +You can host your custom scalar specification on the GraphQL Foundation owned domain [scalars.graphql.org](https://scalars.graphql.org/), see how to add your specification on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). In this example, a custom scalar type for `UUID` is defined with a URL pointing to the relevant IETF specification. ```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") ``` From c822e9cf4cdfa56020a9d259f9d9adee07a3bd6a Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 17 Jan 2023 10:07:47 +1100 Subject: [PATCH 2/7] Update spec/Section 3 -- Type System.md Co-authored-by: Benjie --- spec/Section 3 -- Type System.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 79ae7443a..566680c68 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -410,7 +410,9 @@ scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-ti 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. You can host your custom scalar specification on the GraphQL Foundation owned domain [scalars.graphql.org](https://scalars.graphql.org/), see how to add your specification on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). +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 From f6bce487fa6ab37851a7a021ed63353abc3e1466 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 17 Jan 2023 10:14:16 +1100 Subject: [PATCH 3/7] Remove extra link --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 566680c68..9273f648e 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -395,7 +395,7 @@ valid URL. :: 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. See more on the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). +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 From bb7acf0ac4b3836082bce142fd6107037fd95e2e Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 17 Jan 2023 10:14:47 +1100 Subject: [PATCH 4/7] Update spec/Section 3 -- Type System.md Co-authored-by: Benjie --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 9273f648e..4932bef77 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -422,7 +422,7 @@ 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. See the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). +examples in their description; see the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) for more guidance. **Result Coercion and Serialization** From f190d2103694731ab17b85b3213a4a7c1a8a523f Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 17 Jan 2023 10:15:46 +1100 Subject: [PATCH 5/7] Update spec/Section 3 -- Type System.md Co-authored-by: Benjie --- spec/Section 3 -- Type System.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 4932bef77..85c7ee27c 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2111,9 +2111,9 @@ The `@specifiedBy` _built-in directive_ is used within the type system definition language 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. See more on the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) and see [custom scalar specification templates](https://scalars.graphql.org/) at [scalars.graphql.org](https://scalars.graphql.org/). This directive must not appear on built-in scalar types. +coercion rules. It must not appear on built-in scalar types. -You can host your custom scalar specification on the GraphQL Foundation owned domain [scalars.graphql.org](https://scalars.graphql.org/), see how to add your specification on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). +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. From b81953a9af38e4f1ec50297a956b9e463f406a61 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 24 Jan 2023 09:40:34 +1100 Subject: [PATCH 6/7] Update spec/Section 3 -- Type System.md Co-authored-by: Benjie --- spec/Section 3 -- Type System.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 85c7ee27c..edf1c85f6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2120,6 +2120,4 @@ to the relevant IETF specification. ```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") ``` From 3671a9600bb28207ba6a61d23d800f935f0c9776 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Tue, 24 Jan 2023 09:50:45 +1100 Subject: [PATCH 7/7] Appease Prettier --- spec/Section 3 -- Type System.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index edf1c85f6..a6f7122db 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -405,14 +405,16 @@ 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") +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/). +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 @@ -422,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; see the GraphQL scalars [implementation guide](https://scalars.graphql.org/implementation-guide) for more guidance. +examples in their description; see the GraphQL scalars +[implementation guide](https://scalars.graphql.org/implementation-guide) for +more guidance. **Result Coercion and Serialization** @@ -2113,7 +2117,8 @@ 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). +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.