From 5a2e3e3ba538250e7c376e24c3d4544ecfc9c956 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 7 Aug 2019 14:58:32 -0400 Subject: [PATCH 01/25] First draft of spec changes for the scalar RFC --- spec/Appendix B -- Grammar Summary.md | 7 +++++-- spec/Section 3 -- Type System.md | 24 ++++++++++++++++++++---- spec/Section 4 -- Introspection.md | 9 +++++++-- 3 files changed, 32 insertions(+), 8 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 43a5bd632..b0d17be64 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -253,10 +253,13 @@ TypeExtension : - EnumTypeExtension - InputObjectTypeExtension -ScalarTypeDefinition : Description? scalar Name Directives[Const]? +ScalarTypeDefinition : Description? scalar Name URI? Directives[Const]? + +URI : StringValue but compliant with RFC3986 ScalarTypeExtension : - - extend scalar Name Directives[Const] + - extend scalar Name URI + - extend scalar Name URI? Directives[Const] ObjectTypeDefinition : - Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index fe98bcb7b..083c9cc89 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -352,7 +352,9 @@ represent additional fields a GraphQL client only accesses locally. ## Scalars -ScalarTypeDefinition : Description? scalar Name Directives[Const]? +ScalarTypeDefinition : Description? scalar Name URI? Directives[Const]? + +URI : StringValue but compliant with RFC3986 Scalar types represent primitive leaf values in a GraphQL type system. GraphQL responses take the form of a hierarchical tree; the leaves of this tree are @@ -367,9 +369,20 @@ client-specific primitive for time. Another example of a potentially useful custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. +When providing an additional scalar, GraphQL systems should provide an +RFC3986-compliant URI pointing to a human-readable specification of the data +format, serialization, and coercion rules for the scalar. When a specification +is provided, systems must conform to the described rules. For +example, a GraphQL system providing a `Date` or `DateTime` scalar might link to +TODO Andi's DateTime spec. + +The specification should be stable, i.e. if the format is in flux, the system +should link to a fixed version rather than to a resource whose contents might +change. + ```graphql example -scalar Time -scalar Url +scalar Time "TODO Andi's spec" +scalar Url "https://tools.ietf.org/html/rfc3986" ``` **Built-in Scalars** @@ -572,7 +585,8 @@ type. ### Scalar Extensions ScalarTypeExtension : - - extend scalar Name Directives[Const] + - extend scalar Name URI + - extend scalar Name URI? Directives[Const] Scalar type extensions are used to represent a scalar type which has been extended from some original scalar type. For example, this might be used by a @@ -585,6 +599,8 @@ Scalar type extensions have the potential to be invalid if incorrectly defined. 1. The named type must already be defined and must be a Scalar type. 2. Any non-repeatable directives provided must not already apply to the original Scalar type. +3. If a specification URI is provided, the original Scalar type must not have a + defined specification URI. ## Objects diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index a4ee7d11c..344bb924b 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -150,6 +150,9 @@ type __Type { # should be non-null for NON_NULL and LIST only, must be null for the others ofType: __Type + + # should be non-null for SCALAR only, must be null for the others + specificationUri: String } type __Field { @@ -238,13 +241,15 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should describe the data format and scalar coercion -rules in the description field of any scalar. +A GraphQL type designer should provide a specification URI describing the data +format, serialization, and coercion rules for the scalar. It is recommended to +also summarize the format and provide an example in the description field. Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. +* `specificationUri` may return an RFC3986-compliant URI or {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 2e24437932a0d27ce3e59ed951d86f51f90881c9 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Thu, 15 Aug 2019 15:47:37 -0400 Subject: [PATCH 02/25] Add a bit about changing the URI As Benjie noted, it's a bad idea (though not strictly breaking, if the spec has simply moved). Also tidy up the previous paragraph a bit. --- spec/Section 3 -- Type System.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 083c9cc89..569565d0a 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -369,16 +369,19 @@ client-specific primitive for time. Another example of a potentially useful custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. -When providing an additional scalar, GraphQL systems should provide an +When defining an additional scalar, GraphQL systems should provide an RFC3986-compliant URI pointing to a human-readable specification of the data -format, serialization, and coercion rules for the scalar. When a specification -is provided, systems must conform to the described rules. For -example, a GraphQL system providing a `Date` or `DateTime` scalar might link to -TODO Andi's DateTime spec. - -The specification should be stable, i.e. if the format is in flux, the system -should link to a fixed version rather than to a resource whose contents might -change. +format, serialization, and coercion rules for the scalar. For example, a GraphQL +system providing a `Date` or `DateTime` scalar might link to +TODO Andi's DateTime spec. If a specification URI is present, systems must +conform to the described rules. + +Specifications linked in this way should be stable. This means that if the +specification is in flux, the system should link to a fixed version rather than +to a resource whose contents might change. It is also recommended that the URI +associated with a scalar not be changed once defined; doing so is likely to +disrupt tooling, and may come with changes to the specification contents which +are themselves breaking. ```graphql example scalar Time "TODO Andi's spec" From 1d1cf957d64e593b533ffdaac5b9afffd9559fca Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Mon, 11 Nov 2019 14:40:09 -0500 Subject: [PATCH 03/25] Clarify some points raised at working group --- spec/Section 3 -- Type System.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 569565d0a..8e1333f09 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -372,19 +372,21 @@ the service to be a valid URL. When defining an additional scalar, GraphQL systems should provide an RFC3986-compliant URI pointing to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL -system providing a `Date` or `DateTime` scalar might link to -TODO Andi's DateTime spec. If a specification URI is present, systems must -conform to the described rules. +system providing a `Date` or `DateTime` scalar might link to RFC 3339, or some +document defining a reasonable subset of that RFC. If a specification +URI is present, systems must conform to the described rules. Built-in scalar +types should not provide a URI. Specifications linked in this way should be stable. This means that if the specification is in flux, the system should link to a fixed version rather than to a resource whose contents might change. It is also recommended that the URI associated with a scalar not be changed once defined; doing so is likely to disrupt tooling, and may come with changes to the specification contents which -are themselves breaking. +are themselves breaking. Finally, linked documents should only specify a single +scalar format to avoid ambiguity. ```graphql example -scalar Time "TODO Andi's spec" +scalar Time "https://tools.ietf.org/html/rfc3339" scalar Url "https://tools.ietf.org/html/rfc3986" ``` From 22d292169124ce915b7454169442b8ae9aef560c Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 20 Nov 2019 14:43:06 -0500 Subject: [PATCH 04/25] switch to a directive --- spec/Appendix B -- Grammar Summary.md | 7 +-- spec/Section 3 -- Type System.md | 72 ++++++++++++++++++--------- spec/Section 4 -- Introspection.md | 11 ++-- 3 files changed, 56 insertions(+), 34 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index b0d17be64..43a5bd632 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -253,13 +253,10 @@ TypeExtension : - EnumTypeExtension - InputObjectTypeExtension -ScalarTypeDefinition : Description? scalar Name URI? Directives[Const]? - -URI : StringValue but compliant with RFC3986 +ScalarTypeDefinition : Description? scalar Name Directives[Const]? ScalarTypeExtension : - - extend scalar Name URI - - extend scalar Name URI? Directives[Const] + - extend scalar Name Directives[Const] ObjectTypeDefinition : - Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 8e1333f09..6ba4defc9 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -352,9 +352,7 @@ represent additional fields a GraphQL client only accesses locally. ## Scalars -ScalarTypeDefinition : Description? scalar Name URI? Directives[Const]? - -URI : StringValue but compliant with RFC3986 +ScalarTypeDefinition : Description? scalar Name Directives[Const]? Scalar types represent primitive leaf values in a GraphQL type system. GraphQL responses take the form of a hierarchical tree; the leaves of this tree are @@ -369,25 +367,17 @@ client-specific primitive for time. Another example of a potentially useful custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. -When defining an additional scalar, GraphQL systems should provide an -RFC3986-compliant URI pointing to a human-readable specification of the data -format, serialization, and coercion rules for the scalar. For example, a GraphQL -system providing a `Date` or `DateTime` scalar might link to RFC 3339, or some -document defining a reasonable subset of that RFC. If a specification -URI is present, systems must conform to the described rules. Built-in scalar -types should not provide a URI. - -Specifications linked in this way should be stable. This means that if the -specification is in flux, the system should link to a fixed version rather than -to a resource whose contents might change. It is also recommended that the URI -associated with a scalar not be changed once defined; doing so is likely to -disrupt tooling, and may come with changes to the specification contents which -are themselves breaking. Finally, linked documents should only specify a single -scalar format to avoid ambiguity. +When defining an additional scalar, GraphQL systems should use the `@specified` +directive to provide an RFC3986-compliant URI pointing to a human-readable +specification of the data format, serialization, and coercion rules for the +scalar. For example, a GraphQL system providing a `Date` or `DateTime` scalar +might link to RFC 3339, or some document defining a reasonable subset of that +RFC. If a specification URI is present, systems must conform to the described +rules. Built-in scalar types should not provide a URI. ```graphql example -scalar Time "https://tools.ietf.org/html/rfc3339" -scalar Url "https://tools.ietf.org/html/rfc3986" +scalar Time @specified(by: "https://tools.ietf.org/html/rfc3339") +scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") ``` **Built-in Scalars** @@ -590,8 +580,7 @@ type. ### Scalar Extensions ScalarTypeExtension : - - extend scalar Name URI - - extend scalar Name URI? Directives[Const] + - extend scalar Name Directives[Const] Scalar type extensions are used to represent a scalar type which has been extended from some original scalar type. For example, this might be used by a @@ -604,8 +593,6 @@ Scalar type extensions have the potential to be invalid if incorrectly defined. 1. The named type must already be defined and must be a Scalar type. 2. Any non-repeatable directives provided must not already apply to the original Scalar type. -3. If a specification URI is provided, the original Scalar type must not have a - defined specification URI. ## Objects @@ -1871,6 +1858,10 @@ GraphQL implementations that support the type system definition language must provide the `@deprecated` directive if representing deprecated portions of the schema. +GraphQL implementations that support the type system definition language should +provide the `@specified` directive if representing custom scalar +definitions. + **Custom Directives** GraphQL services and client tooling may provide additional directives beyond @@ -2033,3 +2024,36 @@ type ExampleType { oldField: String @deprecated(reason: "Use `newField`.") } ``` + + +### @specified + +```graphql +directive @specified( + by: String! +) on SCALAR +``` + +The `@specified` directive is used within the type system definition language +to provide an RFC3986-compliant URI for specifying the behaviour of custom +scalar definitions. The URI should point to a human-readable specification of +the data format, serialization, and coercion rules for the scalar. For example, +a GraphQL system providing a `Date` or `DateTime` scalar might link to RFC 3339, +or some document defining a reasonable subset of that RFC. If a specification +URI is present, systems must conform to the described rules. Built-in scalar +types should not provide a URI in this way. + +Specifications linked in this way should provide a single, stable scalar format +to avoid ambiguity. This means that if the specification is in flux, the system +should link to a fixed version rather than to a resource whose contents might +change. It is also recommended that the URI associated with a scalar not be +changed once defined; doing so is likely to disrupt tooling, and may come with +changes to the specification contents which are themselves breaking. + +In this example, two custom scalar types are defined with URIs pointing to the +relevant IETF specifications. + +```graphql example +scalar Time @specified(by: "https://tools.ietf.org/html/rfc3339") +scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") +``` diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 344bb924b..1c956ad7a 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -152,7 +152,7 @@ type __Type { ofType: __Type # should be non-null for SCALAR only, must be null for the others - specificationUri: String + specifiedBy: String } type __Field { @@ -241,15 +241,16 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should provide a specification URI describing the data -format, serialization, and coercion rules for the scalar. It is recommended to -also summarize the format and provide an example in the description field. +A GraphQL type designer should provide use the `@specified` directive to provide +a specification URI describing the data format, serialization, and coercion +rules for the scalar. It is recommended to also summarize the format and provide +an example in the description field. Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specificationUri` may return an RFC3986-compliant URI or {null}. +* `specifiedBy` may return an RFC3986-compliant URI or {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 9a599f64b4accf879652aa47f7ab9f75351fb851 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Tue, 26 Nov 2019 16:55:12 -0500 Subject: [PATCH 05/25] Minor fixes based on feedback --- spec/Section 3 -- Type System.md | 4 ++-- spec/Section 4 -- Introspection.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 6ba4defc9..4febd3fc0 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -376,7 +376,7 @@ RFC. If a specification URI is present, systems must conform to the described rules. Built-in scalar types should not provide a URI. ```graphql example -scalar Time @specified(by: "https://tools.ietf.org/html/rfc3339") +scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339") scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") ``` @@ -2054,6 +2054,6 @@ In this example, two custom scalar types are defined with URIs pointing to the relevant IETF specifications. ```graphql example -scalar Time @specified(by: "https://tools.ietf.org/html/rfc3339") +scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339") scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") ``` diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 1c956ad7a..38cd9cba0 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -241,7 +241,7 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should provide use the `@specified` directive to provide +A GraphQL type designer should use the `@specified` directive to provide a specification URI describing the data format, serialization, and coercion rules for the scalar. It is recommended to also summarize the format and provide an example in the description field. From bc9a408f44cda309cce9f6ab65332b4625f46cb5 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Tue, 10 Dec 2019 13:38:01 -0500 Subject: [PATCH 06/25] Use "URL" instead of "RFC3986-compliant URI" They're not quite the same thing, but URL is what we actually mean even if it's less formally specified. --- spec/Section 3 -- Type System.md | 4 ++-- spec/Section 4 -- Introspection.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 4febd3fc0..63c5ac5e1 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -368,7 +368,7 @@ custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. When defining an additional scalar, GraphQL systems should use the `@specified` -directive to provide an RFC3986-compliant URI pointing to a human-readable +directive to provide a URL pointing to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL system providing a `Date` or `DateTime` scalar might link to RFC 3339, or some document defining a reasonable subset of that @@ -2035,7 +2035,7 @@ directive @specified( ``` The `@specified` directive is used within the type system definition language -to provide an RFC3986-compliant URI for specifying the behaviour of custom +to provide a URL for specifying the behaviour of custom scalar definitions. The URI should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL system providing a `Date` or `DateTime` scalar might link to RFC 3339, diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 38cd9cba0..322db9766 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -250,7 +250,7 @@ Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specifiedBy` may return an RFC3986-compliant URI or {null}. +* `specifiedBy` may return a URL or {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 2c2057e416799c23abe1c0e7157fb5241c8163b3 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Tue, 10 Dec 2019 13:45:12 -0500 Subject: [PATCH 07/25] Tweak introspection language Not all scalars will have a `specifiedBy` value so "should" was too strong. --- spec/Section 4 -- Introspection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 322db9766..ffa2393f4 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -151,7 +151,7 @@ type __Type { # should be non-null for NON_NULL and LIST only, must be null for the others ofType: __Type - # should be non-null for SCALAR only, must be null for the others + # may be non-null for SCALAR only, must be null for the others specifiedBy: String } From a62071879328c2cd860b3f1c113c572337fabe14 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Tue, 10 Dec 2019 13:59:17 -0500 Subject: [PATCH 08/25] Use UUID as a less controversial example Also fix a few more URI->URL references. --- spec/Section 3 -- Type System.md | 32 +++++++++++++++--------------- spec/Section 4 -- Introspection.md | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 63c5ac5e1..beaa98724 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -368,16 +368,16 @@ custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. When defining an additional scalar, GraphQL systems should use the `@specified` -directive to provide a URL pointing to a human-readable -specification of the data format, serialization, and coercion rules for the -scalar. For example, a GraphQL system providing a `Date` or `DateTime` scalar -might link to RFC 3339, or some document defining a reasonable subset of that -RFC. If a specification URI is present, systems must conform to the described -rules. Built-in scalar types should not provide a URI. +directive to provide a URL pointing to a human-readable specification of the +data format, serialization, and coercion rules for the scalar. For example, a +GraphQL system providing a `UUID` scalar might link to RFC 4122, or some +document defining a reasonable subset of that RFC. If a specification URL is +present, systems must conform to the described rules. Built-in scalar types +should not provide a URL. ```graphql example -scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339") -scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") +scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122") +scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986") ``` **Built-in Scalars** @@ -2036,24 +2036,24 @@ directive @specified( The `@specified` directive is used within the type system definition language to provide a URL for specifying the behaviour of custom -scalar definitions. The URI should point to a human-readable specification of +scalar definitions. The URL should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, -a GraphQL system providing a `Date` or `DateTime` scalar might link to RFC 3339, +a GraphQL system providing a `UUID` scalar might link to RFC 4122, or some document defining a reasonable subset of that RFC. If a specification -URI is present, systems must conform to the described rules. Built-in scalar -types should not provide a URI in this way. +URL is present, systems must conform to the described rules. Built-in scalar +types should not provide a URL in this way. Specifications linked in this way should provide a single, stable scalar format to avoid ambiguity. This means that if the specification is in flux, the system should link to a fixed version rather than to a resource whose contents might -change. It is also recommended that the URI associated with a scalar not be +change. It is also recommended that the URL associated with a scalar not be changed once defined; doing so is likely to disrupt tooling, and may come with changes to the specification contents which are themselves breaking. -In this example, two custom scalar types are defined with URIs pointing to the +In this example, two custom scalar types are defined with URLs pointing to the relevant IETF specifications. ```graphql example -scalar DateTime @specified(by: "https://tools.ietf.org/html/rfc3339") -scalar Url @specified(by: "https://tools.ietf.org/html/rfc3986") +scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122") +scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986") ``` diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index ffa2393f4..b1dcf0a2c 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -242,7 +242,7 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. A GraphQL type designer should use the `@specified` directive to provide -a specification URI describing the data format, serialization, and coercion +a specification URL describing the data format, serialization, and coercion rules for the scalar. It is recommended to also summarize the format and provide an example in the description field. From 5522c9a2ac97806f0192b634c54cabe8c5a570a5 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Mon, 16 Dec 2019 10:50:31 -0500 Subject: [PATCH 09/25] Update directive name to @specifiedBy --- spec/Section 3 -- Type System.md | 32 +++++++++++++++--------------- spec/Section 4 -- Introspection.md | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index beaa98724..d51e2aee0 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -367,17 +367,17 @@ client-specific primitive for time. Another example of a potentially useful custom scalar is `Url`, which serializes as a string, but is guaranteed by the service to be a valid URL. -When defining an additional scalar, GraphQL systems should use the `@specified` -directive to provide a URL pointing to a human-readable specification of the -data format, serialization, and coercion rules for the scalar. For example, a -GraphQL system providing a `UUID` scalar might link to RFC 4122, or some -document defining a reasonable subset of that RFC. If a specification URL is -present, systems must conform to the described rules. Built-in scalar types -should not provide a URL. +When defining an additional scalar, GraphQL systems should use the +`@specifiedBy` directive to provide a URL pointing to a human-readable +specification of the data format, serialization, and coercion rules for the +scalar. For example, a GraphQL system providing a `UUID` scalar might link to +RFC 4122, or some document defining a reasonable subset of that RFC. If a +specification URL is present, systems must conform to the described rules. +Built-in scalar types should not provide a URL. ```graphql example -scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122") -scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986") +scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") +scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986") ``` **Built-in Scalars** @@ -1859,7 +1859,7 @@ provide the `@deprecated` directive if representing deprecated portions of the schema. GraphQL implementations that support the type system definition language should -provide the `@specified` directive if representing custom scalar +provide the `@specifiedBy` directive if representing custom scalar definitions. **Custom Directives** @@ -2026,15 +2026,15 @@ type ExampleType { ``` -### @specified +### @specifiedBy ```graphql -directive @specified( - by: String! +directive @specifiedBy( + url: String! ) on SCALAR ``` -The `@specified` directive is used within the type system definition language +The `@specifiedBy` directive is used within the type system definition language to provide a URL for specifying the behaviour of custom scalar definitions. The URL should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, @@ -2054,6 +2054,6 @@ In this example, two custom scalar types are defined with URLs pointing to the relevant IETF specifications. ```graphql example -scalar UUID @specified(by: "https://tools.ietf.org/html/rfc4122") -scalar URL @specified(by: "https://tools.ietf.org/html/rfc3986") +scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") +scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986") ``` diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index b1dcf0a2c..73bd53f82 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -241,7 +241,7 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should use the `@specified` directive to provide +A GraphQL type designer should use the `@specifiedBy` directive to provide a specification URL describing the data format, serialization, and coercion rules for the scalar. It is recommended to also summarize the format and provide an example in the description field. From 2ed504314cb30a439699e8fd8e053d7d7f6ef19d Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Mon, 16 Dec 2019 10:52:16 -0500 Subject: [PATCH 10/25] Tweak language --- spec/Section 4 -- Introspection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 73bd53f82..a3c65e8ff 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -250,7 +250,7 @@ Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specifiedBy` may return a URL or {null}. +* `specifiedBy` may return a String (in the form of a URL) or {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 50b551014bfa171f46108d106bfe0c14750a138a Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 5 Feb 2020 15:39:28 -0500 Subject: [PATCH 11/25] Americanize spelling in spec/Section 3 -- Type System.md Co-Authored-By: Matt Farmer --- 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 d51e2aee0..9f8496602 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2035,7 +2035,7 @@ directive @specifiedBy( ``` The `@specifiedBy` directive is used within the type system definition language -to provide a URL for specifying the behaviour of custom +to provide a URL for specifying the behavior of custom scalar definitions. The URL should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL system providing a `UUID` scalar might link to RFC 4122, From e235752f43500b7c731a33b4b71fdf30d6415cf1 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 5 Feb 2020 15:43:39 -0500 Subject: [PATCH 12/25] Add link to RFC4122 Co-Authored-By: Lee Byron --- 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 9f8496602..f5f25a360 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2038,7 +2038,7 @@ The `@specifiedBy` directive is used within the type system definition language to provide a URL for specifying the behavior of custom scalar definitions. The URL should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, -a GraphQL system providing a `UUID` scalar might link to RFC 4122, +a GraphQL system providing a `UUID` scalar might link to [RFC 4122](https://tools.ietf.org/html/rfc4122), or some document defining a reasonable subset of that RFC. If a specification URL is present, systems must conform to the described rules. Built-in scalar types should not provide a URL in this way. From 42360e405000b1fcbefbaa48faad3bcfdc1af547 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 5 Feb 2020 15:45:25 -0500 Subject: [PATCH 13/25] Update spec/Section 4 -- Introspection.md Co-Authored-By: Lee Byron --- spec/Section 4 -- Introspection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index a3c65e8ff..d6ebd8902 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -241,7 +241,7 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should use the `@specifiedBy` directive to provide +A GraphQL type designer should define `specifiedBy` for custom scalars as a specification URL describing the data format, serialization, and coercion rules for the scalar. It is recommended to also summarize the format and provide an example in the description field. From 4b5a285bd49a234c5bc5dbe20152e6c5729634e8 Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Wed, 5 Feb 2020 15:48:48 -0500 Subject: [PATCH 14/25] Minor wording and formatting tweaks --- spec/Section 3 -- Type System.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index f5f25a360..c1793cb4b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -364,7 +364,7 @@ could define a scalar called `Time` which, while serialized as a string, promises to conform to ISO-8601. When querying a field of type `Time`, you can then rely on the ability to parse the result with an ISO-8601 parser and use a client-specific primitive for time. Another example of a potentially useful -custom scalar is `Url`, which serializes as a string, but is guaranteed by +custom scalar is `URL`, which serializes as a string, but is guaranteed by the service to be a valid URL. When defining an additional scalar, GraphQL systems should use the @@ -372,8 +372,8 @@ When defining an additional scalar, GraphQL systems should use the specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL system providing a `UUID` scalar might link to RFC 4122, or some document defining a reasonable subset of that RFC. If a -specification URL is present, systems must conform to the described rules. -Built-in scalar types should not provide a URL. +specification URL is present, systems and tools that are aware of it should +conform to its described rules. Built-in scalar types should not provide a URL. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") @@ -2029,9 +2029,7 @@ type ExampleType { ### @specifiedBy ```graphql -directive @specifiedBy( - url: String! -) on SCALAR +directive @specifiedBy(url: String!) on SCALAR ``` The `@specifiedBy` directive is used within the type system definition language @@ -2040,8 +2038,8 @@ scalar definitions. The URL should point to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL system providing a `UUID` scalar might link to [RFC 4122](https://tools.ietf.org/html/rfc4122), or some document defining a reasonable subset of that RFC. If a specification -URL is present, systems must conform to the described rules. Built-in scalar -types should not provide a URL in this way. +URL is present, systems and tools that are aware of it should conform to its +described rules. Built-in scalar types should not provide a URL in this way. Specifications linked in this way should provide a single, stable scalar format to avoid ambiguity. This means that if the specification is in flux, the system From 968f9613bee2d50a20b05b3eeb4fa1d522e6022e Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 09:16:02 -0800 Subject: [PATCH 15/25] Editorial --- spec/Section 4 -- Introspection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index d6ebd8902..5081f833a 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -151,7 +151,7 @@ type __Type { # should be non-null for NON_NULL and LIST only, must be null for the others ofType: __Type - # may be non-null for SCALAR only, must be null for the others + # should be non-null for SCALAR only, must be null for the others specifiedBy: String } @@ -250,7 +250,7 @@ Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specifiedBy` may return a String (in the form of a URL) or {null}. +* `specifiedBy` may return a String (in the form of a URL), otherwise must be {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 6c580941d477ed7d232503c4e0a24b193b546483 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 09:30:28 -0800 Subject: [PATCH 16/25] Editorial for Scalars section --- spec/Section 3 -- Type System.md | 47 +++++++++++++++++++------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index c1793cb4b..64f46393d 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -358,8 +358,32 @@ Scalar types represent primitive leaf values in a GraphQL type system. GraphQL responses take the form of a hierarchical tree; the leaves of this tree are typically GraphQL Scalar types (but may also be Enum types or {null} values). -GraphQL provides a number of built-in scalars (see below), but type systems can -add additional scalars with semantic meaning. For example, a GraphQL system +GraphQL provides a number of built-in scalars which are fully defined in the +sections below, however type systems may also add additional custom scalars to +introduce additional semantic meaning (see below). + +**Built-in Scalars** + +GraphQL specifies a basic set of well-defined Scalar types: {Int}, {Float}, +{String}, {Boolean}, and {ID}. A GraphQL framework should support all of these +types, and a GraphQL service which provides a type by these names must adhere to +the behavior described for them in this document. As an example, a service must +not include a type called {Int} and use it to represent 64-bit numbers, +internationalization information, or anything other than what is defined in +this document. + +When returning the set of types from the `__Schema` introspection type, all +referenced built-in scalars must be included. If a built-in scalar type is not +referenced anywhere in a schema (there is no field, argument, or input field of +that type) then it must not be included. + +When representing a GraphQL schema using the type system definition language, +all built-in scalars must be omitted for brevity. + +**Custom Scalars** + +GraphQL services may use custom scalar types in addition to the built-in +scalars. For example, a GraphQL system could define a scalar called `Time` which, while serialized as a string, promises to conform to ISO-8601. When querying a field of type `Time`, you can then rely on the ability to parse the result with an ISO-8601 parser and use a @@ -380,23 +404,8 @@ scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986") ``` -**Built-in Scalars** - -GraphQL specifies a basic set of well-defined Scalar types: {Int}, {Float}, -{String}, {Boolean}, and {ID}. A GraphQL framework should support all of these -types, and a GraphQL service which provides a type by these names must adhere to -the behavior described for them in this document. As an example, a service must -not include a type called {Int} and use it to represent 64-bit numbers, -internationalization information, or anything other than what is defined in -this document. - -When returning the set of types from the `__Schema` introspection type, all -referenced built-in scalars must be included. If a built-in scalar type is not -referenced anywhere in a schema (there is no field, argument, or input field of -that type) then it must not be included. - -When representing a GraphQL schema using the type system definition language, -all built-in scalars must be omitted for brevity. +Built-in scalar types must not provide a specification URL as they are specified +by this document. **Result Coercion and Serialization** From bab4fabd4369e4fd3db871c49a892ab32e4e7de9 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:03:42 -0800 Subject: [PATCH 17/25] Editorial to reduce duplication and centralize info --- spec/Section 3 -- Type System.md | 61 +++++++++++++++----------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 64f46393d..8fd83a604 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -383,27 +383,34 @@ all built-in scalars must be omitted for brevity. **Custom Scalars** GraphQL services may use custom scalar types in addition to the built-in -scalars. For example, a GraphQL system -could define a scalar called `Time` which, while serialized as a string, -promises to conform to ISO-8601. When querying a field of type `Time`, you can -then rely on the ability to parse the result with an ISO-8601 parser and use a -client-specific primitive for time. Another example of a potentially useful -custom scalar is `URL`, which serializes as a string, but is guaranteed by -the service to be a valid URL. - -When defining an additional scalar, GraphQL systems should use the -`@specifiedBy` directive to provide a URL pointing to a human-readable -specification of the data format, serialization, and coercion rules for the -scalar. For example, a GraphQL system providing a `UUID` scalar might link to -RFC 4122, or some document defining a reasonable subset of that RFC. If a -specification URL is present, systems and tools that are aware of it should -conform to its described rules. Built-in scalar types should not provide a URL. +scalars. For example, a GraphQL service could define a scalar called `Time` +which, while serialized as a string, conforms to ISO-8601. When querying a field +of type `Time`, you can then rely on the ability to parse the result with an +ISO-8601 parser and use a client-specific primitive for time. 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 `specifiedBy` introspection field or the `@specifiedBy` directive. 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 specifications URLs should not be changed once defined; doing so +is likely to disrupt tooling or may come with 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. @@ -2042,25 +2049,13 @@ 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 custom -scalar definitions. The URL should point to a human-readable specification of -the data format, serialization, and coercion rules for the scalar. For example, -a GraphQL system providing a `UUID` scalar might link to [RFC 4122](https://tools.ietf.org/html/rfc4122), -or some document defining a reasonable subset of that RFC. If a specification -URL is present, systems and tools that are aware of it should conform to its -described rules. Built-in scalar types should not provide a URL in this way. - -Specifications linked in this way should provide a single, stable scalar format -to avoid ambiguity. This means that if the specification is in flux, the system -should link to a fixed version rather than to a resource whose contents might -change. It is also recommended that the URL associated with a scalar not be -changed once defined; doing so is likely to disrupt tooling, and may come with -changes to the specification contents which are themselves breaking. - -In this example, two custom scalar types are defined with URLs pointing to the -relevant IETF specifications. +to provide a 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. + +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") ``` From 038b6f8bd02dd71113bc0b02eae6f0bd6a858d68 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:08:48 -0800 Subject: [PATCH 18/25] Editorial - grammar --- 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 8fd83a604..38faf699d 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -407,7 +407,7 @@ 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 specifications URLs should not be changed once defined; doing so +Custom scalar specification URLs should not be changed once defined; as doing so is likely to disrupt tooling or may come with breaking changes within the linked specification's contents. From eb18c03887cf417fe4a76c1864251cf0c583ae4c Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:17:00 -0800 Subject: [PATCH 19/25] Editorial - simplify introspection change --- spec/Section 4 -- Introspection.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 5081f833a..9e30d536b 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -241,16 +241,15 @@ actually valid. These kinds are listed in the `__TypeKind` enumeration. Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. -A GraphQL type designer should define `specifiedBy` for custom scalars as -a specification URL describing the data format, serialization, and coercion -rules for the scalar. It is recommended to also summarize the format and provide -an example in the description field. +Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide +`specifiedBy` as a scalar specification URL. Fields * `kind` must return `__TypeKind.SCALAR`. * `name` must return a String. -* `specifiedBy` may return a String (in the form of a URL), otherwise must be {null}. +* `specifiedBy` may return a String (in the form of a URL) for custom scalars, + otherwise must be {null}. * `description` may return a String or {null}. * All other fields must return {null}. From 96fb0d1c7605ad50f9250e14b2d304d096b01600 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:18:50 -0800 Subject: [PATCH 20/25] Editorial - introspection description --- spec/Section 4 -- Introspection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 9e30d536b..42572ed9c 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -151,7 +151,7 @@ type __Type { # should be non-null for NON_NULL and LIST only, must be null for the others ofType: __Type - # should be non-null for SCALAR only, must be null for the others + # should be non-null for custom SCALAR only, must be null for the others specifiedBy: String } From f8065c391dc61be67342da661f65d1ec40917020 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:21:07 -0800 Subject: [PATCH 21/25] Editorial - return note about use of descriptions --- spec/Section 3 -- Type System.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 38faf699d..c45fda717 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -414,6 +414,9 @@ linked specification's contents. Built-in scalar types must not provide a specification URL as they are specified by this document. +Note: Custom scalars should also summarize the specified format and provide +examples in their description. + **Result Coercion and Serialization** A GraphQL service, when preparing a field of a given scalar type, must uphold the From a2401b7268cc5899504b8ddfb75be0951523848b Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:23:40 -0800 Subject: [PATCH 22/25] Editorial - directive description --- spec/Section 3 -- Type System.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index c45fda717..d48f11253 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2052,9 +2052,16 @@ directive @specifiedBy(url: String!) on SCALAR ``` The `@specifiedBy` directive is used within the type system definition language +<<<<<<< HEAD to provide a 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. +======= +to provide a 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 not appear on built-in scalar types. +>>>>>>> 2a3ae75... Editorial - directive description In this example, a custom scalar type for `UUID` is defined with a URL pointing to the relevant IETF specification. From 318b7530d296b3c574b9de9708e39983abbbff7d Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 11 Jan 2021 10:30:56 -0800 Subject: [PATCH 23/25] Update Section 3 -- Type System.md --- spec/Section 3 -- Type System.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index d48f11253..52192f1da 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -414,7 +414,7 @@ linked specification's contents. Built-in scalar types must not provide a specification URL as they are specified by this document. -Note: Custom scalars should also summarize the specified format and provide +Note: Custom scalars should also summarize the specified format and provide examples in their description. **Result Coercion and Serialization** @@ -2052,16 +2052,10 @@ directive @specifiedBy(url: String!) on SCALAR ``` The `@specifiedBy` directive is used within the type system definition language -<<<<<<< HEAD -to provide a 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. -======= -to provide a 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 not appear on built-in scalar types. ->>>>>>> 2a3ae75... Editorial - directive description +to provide a 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. In this example, a custom scalar type for `UUID` is defined with a URL pointing to the relevant IETF specification. From f2bf007a994cd155f250507891880995f10c79ca Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 8 Apr 2021 23:04:41 -0700 Subject: [PATCH 24/25] address review --- spec/Section 3 -- Type System.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 52192f1da..3822826dd 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -360,7 +360,7 @@ typically GraphQL Scalar types (but may also be Enum types or {null} values). GraphQL provides a number of built-in scalars which are fully defined in the sections below, however type systems may also add additional custom scalars to -introduce additional semantic meaning (see below). +introduce additional semantic meaning. **Built-in Scalars** @@ -391,8 +391,8 @@ 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 `specifiedBy` introspection field or the `@specifiedBy` directive. This -URL must link to a human-readable specification of the data format, +URL via the `specifiedBy` introspection field or the `@specifiedBy` directive. +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, @@ -407,8 +407,8 @@ 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 URLs should not be changed once defined; as doing so -is likely to disrupt tooling or may come with breaking changes within the +Custom scalar specification URLs 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 From 89014b934809e2bfb0da112a9acb5510871b566f Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 8 Apr 2021 23:10:45 -0700 Subject: [PATCH 25/25] additional editorial adjustment --- spec/Section 3 -- Type System.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 3822826dd..e3ca2bb16 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -383,19 +383,19 @@ all built-in scalars must be omitted for brevity. **Custom Scalars** GraphQL services may use custom scalar types in addition to the built-in -scalars. For example, a GraphQL service could define a scalar called `Time` -which, while serialized as a string, conforms to ISO-8601. When querying a field -of type `Time`, you can then rely on the ability to parse the result with an -ISO-8601 parser and use a client-specific primitive for time. 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. +scalars. For example, a GraphQL service could define a scalar called `UUID` +which, while serialized as a string, conforms to [RFC 4122](https://tools.ietf.org/html/rfc4122). +When querying a field of type `UUID`, you can then rely on the ability to parse +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` introspection field or the `@specifiedBy` directive. +URL via the `@specifiedBy` directive or the `specifiedBy` 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, +a reasonable subset of that RFC. If a scalar `specifiedBy` URL is present, systems and tools that are aware of it should conform to its described rules. ```graphql example @@ -411,7 +411,7 @@ Custom scalar specification URLs 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 +Built-in scalar types must not provide a `specifiedBy` URL as they are specified by this document. Note: Custom scalars should also summarize the specified format and provide