From 27e77205538b9c14b6b648f10a9e79af04a1847e Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sat, 26 Oct 2019 20:30:07 +0300 Subject: [PATCH 01/12] Improve clarity of standard directives --- 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 8940956f7..00c03d888 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1692,6 +1692,13 @@ While defining a directive, it must not reference itself directly or indirectly: directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION ``` +When returning the set of directives from the `__Schema` introspection type, both +@skip and @include directives must be included. @deprecated directive may be included +if GraphQL implementation supports the type system definition language. + +When representing a GraphQL schema using the type system definition language, both @skip, +@include and @deprecated directives can be omitted for brevity. + **Validation** 1. A directive definition must not contain the use of a directive which From cecf7fd4ceee653cebb18b2e0aab3933f2ab7fe3 Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sat, 26 Oct 2019 20:33:37 +0300 Subject: [PATCH 02/12] can be -> should be --- 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 00c03d888..a9960b7b0 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1697,7 +1697,7 @@ When returning the set of directives from the `__Schema` introspection type, bot if GraphQL implementation supports the type system definition language. When representing a GraphQL schema using the type system definition language, both @skip, -@include and @deprecated directives can be omitted for brevity. +@include and @deprecated directives should be omitted for brevity. **Validation** From 37df0755b2c48aeef298bdde917e38170c354916 Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sat, 26 Oct 2019 23:38:02 +0300 Subject: [PATCH 03/12] should -> can --- 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 a9960b7b0..00c03d888 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1697,7 +1697,7 @@ When returning the set of directives from the `__Schema` introspection type, bot if GraphQL implementation supports the type system definition language. When representing a GraphQL schema using the type system definition language, both @skip, -@include and @deprecated directives should be omitted for brevity. +@include and @deprecated directives can be omitted for brevity. **Validation** From 14a8c0ff4c09ee94649fc5241f5c3df569a50b63 Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sat, 26 Oct 2019 23:41:26 +0300 Subject: [PATCH 04/12] formatting --- spec/Section 3 -- Type System.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 00c03d888..1cea604e3 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1693,11 +1693,11 @@ directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION ``` When returning the set of directives from the `__Schema` introspection type, both -@skip and @include directives must be included. @deprecated directive may be included +`@skip` and `@include` directives must be included. `@deprecated` directive may be included if GraphQL implementation supports the type system definition language. -When representing a GraphQL schema using the type system definition language, both @skip, -@include and @deprecated directives can be omitted for brevity. +When representing a GraphQL schema using the type system definition language, both `@skip`, +`@include` and `@deprecated` directives can be omitted for brevity. **Validation** From cfe4e35426a495f21a678d4b1351cc1b066f0267 Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sun, 27 Oct 2019 14:39:39 +0300 Subject: [PATCH 05/12] merge notes about standard directives to **built-in directives** --- spec/Section 3 -- Type System.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 1cea604e3..423d1e274 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1644,12 +1644,6 @@ A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator. -GraphQL implementations should provide the `@skip` and `@include` directives. - -GraphQL implementations that support the type system definition language must -provide the `@deprecated` directive if representing deprecated portions of -the schema. - Directives must only be used in the locations they are declared to belong in. In this example, a directive is defined which can be used to annotate a field: @@ -1692,12 +1686,19 @@ While defining a directive, it must not reference itself directly or indirectly: directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION ``` +**Built-in Directives** + +GraphQL implementations should provide the `@skip` and `@include` directives. When returning the set of directives from the `__Schema` introspection type, both -`@skip` and `@include` directives must be included. `@deprecated` directive may be included -if GraphQL implementation supports the type system definition language. +`@skip` and `@include` directives must be included. -When representing a GraphQL schema using the type system definition language, both `@skip`, -`@include` and `@deprecated` directives can be omitted for brevity. +GraphQL implementations that support the type system definition language must +provide the `@deprecated` directive if representing deprecated portions of +the schema, in this case `@deprecated` directive may be included when returning +the set of directives from the `__Schema` introspection type. + +When representing a GraphQL schema using the type system definition language, +both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity. **Validation** @@ -1714,6 +1715,7 @@ When representing a GraphQL schema using the type system definition language, bo 2. The argument must accept a type where {IsInputType(argumentType)} returns {true}. +### ### @skip ```graphql From f5cd6ba805c849ed501390a14f43da0422e7100c Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sun, 27 Oct 2019 14:40:57 +0300 Subject: [PATCH 06/12] typo --- spec/Section 3 -- Type System.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 423d1e274..38e7e29e4 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1715,7 +1715,6 @@ both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity 2. The argument must accept a type where {IsInputType(argumentType)} returns {true}. -### ### @skip ```graphql From f0c1fb70fb4c297e5ad43cb3fb327efb10e28aa6 Mon Sep 17 00:00:00 2001 From: Ivan Maximov Date: Sun, 27 Oct 2019 18:10:12 +0300 Subject: [PATCH 07/12] review --- 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 38e7e29e4..d12749830 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1698,7 +1698,7 @@ the schema, in this case `@deprecated` directive may be included when returning the set of directives from the `__Schema` introspection type. When representing a GraphQL schema using the type system definition language, -both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity. +the built-in directives should be omitted for brevity. **Validation** From f485d894fc207a9a80a06424a58cfa1a61fc42b8 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 22 Apr 2021 10:31:16 -0700 Subject: [PATCH 08/12] Move built-in section above custom section --- spec/Section 3 -- Type System.md | 38 ++++++++++++++++---------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index c36108755..fbeeebf8a 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1875,6 +1875,25 @@ A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator. +**Built-in Directives** + +GraphQL implementations should provide the `@skip` and `@include` directives. +When returning the set of directives from the `__Schema` introspection type, both +`@skip` and `@include` directives must be included. + +GraphQL implementations that support the type system definition language must +provide the `@deprecated` directive if representing deprecated portions of +the schema, in this case `@deprecated` directive may be included when returning +the set of directives from the `__Schema` introspection type. + +GraphQL implementations that support the type system definition language should +provide the `@specifiedBy` directive if representing custom scalar +definitions. + +When representing a GraphQL schema using the type system definition language, +built in directives (any defined in this specification) should be omitted for +brevity. Custom directives in use must be specified. + **Custom Directives** GraphQL services and client tooling may provide additional directives beyond @@ -1951,25 +1970,6 @@ directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION Note: The order in which directives appear may be significant, including repeatable directives. -**Built-in Directives** - -GraphQL implementations should provide the `@skip` and `@include` directives. -When returning the set of directives from the `__Schema` introspection type, both -`@skip` and `@include` directives must be included. - -GraphQL implementations that support the type system definition language must -provide the `@deprecated` directive if representing deprecated portions of -the schema, in this case `@deprecated` directive may be included when returning -the set of directives from the `__Schema` introspection type. - -GraphQL implementations that support the type system definition language should -provide the `@specifiedBy` directive if representing custom scalar -definitions. - -When representing a GraphQL schema using the type system definition language, -built in directives (any defined in this specification) should be omitted for -brevity. Custom directives in use must be specified. - **Validation** 1. A directive definition must not contain the use of a directive which From 4e28da2166ec67a43439bda2205281c74eb72cc8 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 22 Apr 2021 10:43:30 -0700 Subject: [PATCH 09/12] Generalize message and repeat in introspection section --- spec/Section 3 -- Type System.md | 10 +++++----- spec/Section 4 -- Introspection.md | 5 ++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index fbeeebf8a..581d58d9e 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1878,22 +1878,22 @@ by a validator, executor, or client tool such as a code generator. **Built-in Directives** GraphQL implementations should provide the `@skip` and `@include` directives. -When returning the set of directives from the `__Schema` introspection type, both -`@skip` and `@include` directives must be included. GraphQL implementations that support the type system definition language must provide the `@deprecated` directive if representing deprecated portions of -the schema, in this case `@deprecated` directive may be included when returning -the set of directives from the `__Schema` introspection type. +the schema. GraphQL implementations that support the type system definition language should provide the `@specifiedBy` directive if representing custom scalar definitions. When representing a GraphQL schema using the type system definition language, -built in directives (any defined in this specification) should be omitted for +built-in directives (any defined in this specification) should be omitted for brevity. Custom directives in use must be specified. +When introspecting a GraphQL service, all provided directives including built-in +directives must be included in the set of returned directives. + **Custom Directives** GraphQL services and client tooling may provide additional directives beyond diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 2c80a18f4..3a9c6597b 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -429,7 +429,10 @@ Fields ### The __Directive Type -The `__Directive` type represents a Directive that a service supports. +The `__Directive` type represents any Directive that a service supports. + +This includes both [built-in directives](#sec-Type-System.Directives.Built-in-Directives) +and [custom directives](#sec-Type-System.Directives.Custom-Directives). Fields From ca86b8bc12f68994fa37f1d8f58f60f07e9f042f Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 22 Apr 2021 10:57:16 -0700 Subject: [PATCH 10/12] Use term definitions --- spec/Section 2 -- Language.md | 3 +- spec/Section 3 -- Type System.md | 55 +++++++++++++++--------------- spec/Section 4 -- Introspection.md | 3 +- 3 files changed, 30 insertions(+), 31 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 18993170a..48385d543 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -1195,8 +1195,7 @@ fragments and operations. As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. GraphQL services and tools may also provide -additional [custom directives](#sec-Type-System.Directives.Custom-Directives) -beyond those described here. +any additional *custom directive* beyond those described here. **Directive order is significant** diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 581d58d9e..74d0a6ff3 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1877,6 +1877,8 @@ by a validator, executor, or client tool such as a code generator. **Built-in Directives** +:: A *built-in directive* is any directive defined within this specification. + GraphQL implementations should provide the `@skip` and `@include` directives. GraphQL implementations that support the type system definition language must @@ -1887,26 +1889,25 @@ GraphQL implementations that support the type system definition language should provide the `@specifiedBy` directive if representing custom scalar definitions. -When representing a GraphQL schema using the type system definition language, -built-in directives (any defined in this specification) should be omitted for -brevity. Custom directives in use must be specified. +When representing a GraphQL schema using the type system definition language +any *built-in directive* should be omitted for brevity. -When introspecting a GraphQL service, all provided directives including built-in -directives must be included in the set of returned directives. +When introspecting a GraphQL service all provided directives, including +any *built-in directive*, must be included in the set of returned directives. **Custom Directives** -GraphQL services and client tooling may provide additional directives beyond -those defined in this document. Directives are the preferred way to extend -GraphQL with custom or experimental behavior. - -Note: When defining a directive, it is recommended to prefix the directive's -name to make its scope of usage clear and to prevent a collision with directives -which may be specified by future versions of this document (which will not -include `_` in their name). For example, a custom directive used by Facebook's -GraphQL service should be named `@fb_auth` instead of `@auth`. This is -especially recommended for proposed additions to this specification which can -change during the [RFC process](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md). +:: GraphQL services and client tooling may provide any additional +*custom directive* beyond those defined in this document. Directives are the +preferred way to extend GraphQL with custom or experimental behavior. + +Note: When defining a *custom directive*, it is recommended to prefix the +directive's name to make its scope of usage clear and to prevent a collision +with *built-in directive* which may be specified by future versions of this +document (which will not include `_` in their name). For example, a +*custom directive* used by Facebook's GraphQL service should be named `@fb_auth` +instead of `@auth`. This is especially recommended for proposed additions to +this specification which can change during the [RFC process](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md). For example a work in progress version of `@live` should be named `@rfc_live`. Directives must only be used in the locations they are declared to belong in. @@ -1991,8 +1992,8 @@ repeatable directives. directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT ``` -The `@skip` directive may be provided for fields, fragment spreads, and -inline fragments, and allows for conditional exclusion during execution as +The `@skip` *built-in directive* may be provided for fields, fragment spreads, +and inline fragments, and allows for conditional exclusion during execution as described by the if argument. In this example `experimentalField` will only be queried if the variable @@ -2011,9 +2012,9 @@ query myQuery($someTest: Boolean!) { directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT ``` -The `@include` directive may be provided for fields, fragment spreads, and -inline fragments, and allows for conditional inclusion during execution as -described by the if argument. +The `@include` *built-in directive* may be provided for fields, fragment +spreads, and inline fragments, and allows for conditional inclusion during +execution as described by the if argument. In this example `experimentalField` will only be queried if the variable `$someTest` has the value `true` @@ -2040,8 +2041,8 @@ directive @deprecated( ) on FIELD_DEFINITION | ENUM_VALUE ``` -The `@deprecated` directive is used within the type system definition language -to indicate deprecated portions of a GraphQL service's schema, such as +The `@deprecated` *built-in directive* is used within the type system definition +language to indicate deprecated portions of a GraphQL service's schema, such as deprecated fields on a type or deprecated enum values. Deprecations include a reason for why it is deprecated, which is formatted using @@ -2064,10 +2065,10 @@ type ExampleType { directive @specifiedBy(url: String!) on SCALAR ``` -The `@specifiedBy` 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 +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. In this example, a custom scalar type for `UUID` is defined with a URL pointing diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 3a9c6597b..67f162136 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -431,8 +431,7 @@ Fields The `__Directive` type represents any Directive that a service supports. -This includes both [built-in directives](#sec-Type-System.Directives.Built-in-Directives) -and [custom directives](#sec-Type-System.Directives.Custom-Directives). +This includes both any *built-in directive* and any *custom directive*. Fields From 706332ec4d053af12883068c6c994ea87d4f62b8 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 22 Apr 2021 15:18:32 -0700 Subject: [PATCH 11/12] Apply suggestions from code review Co-authored-by: Ivan Maximov --- 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 74d0a6ff3..53962f0a6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1994,7 +1994,7 @@ directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT The `@skip` *built-in directive* may be provided for fields, fragment spreads, and inline fragments, and allows for conditional exclusion during execution as -described by the if argument. +described by the `if` argument. In this example `experimentalField` will only be queried if the variable `$someTest` has the value `false`. @@ -2014,7 +2014,7 @@ directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT The `@include` *built-in directive* may be provided for fields, fragment spreads, and inline fragments, and allows for conditional inclusion during -execution as described by the if argument. +execution as described by the `if` argument. In this example `experimentalField` will only be queried if the variable `$someTest` has the value `true` From 85349136fff790dc80b7b7567ee1f51da7626389 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 23 Apr 2021 12:34:28 -0700 Subject: [PATCH 12/12] may omit built-ins for brevity --- 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 53962f0a6..d164550cc 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1890,7 +1890,7 @@ provide the `@specifiedBy` directive if representing custom scalar definitions. When representing a GraphQL schema using the type system definition language -any *built-in directive* should be omitted for brevity. +any *built-in directive* may be omitted for brevity. When introspecting a GraphQL service all provided directives, including any *built-in directive*, must be included in the set of returned directives.