diff --git a/spec/Appendix C -- Grammar Summary.md b/spec/Appendix C -- Grammar Summary.md index cc464a4a6..3ac20466a 100644 --- a/spec/Appendix C -- Grammar Summary.md +++ b/spec/Appendix C -- Grammar Summary.md @@ -260,6 +260,7 @@ TypeSystemExtension : - SchemaExtension - TypeExtension +- DirectiveExtension SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ } @@ -377,7 +378,9 @@ InputObjectTypeExtension : - extend input Name Directives[Const] [lookahead != `{`] DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? -`repeatable`? on DirectiveLocations +Directives[Const]? `repeatable`? on DirectiveLocations + +DirectiveExtension : extend directive @ Name Directives[Const] DirectiveLocations : @@ -413,6 +416,7 @@ TypeSystemDirectiveLocation : one of - `ENUM_VALUE` - `INPUT_OBJECT` - `INPUT_FIELD_DEFINITION` +- `DIRECTIVE_DEFINITION` ## Schema Coordinate Syntax diff --git a/spec/Appendix D -- Specified Definitions.md b/spec/Appendix D -- Specified Definitions.md index d2242025c..e4a14986b 100644 --- a/spec/Appendix D -- Specified Definitions.md +++ b/spec/Appendix D -- Specified Definitions.md @@ -21,7 +21,7 @@ directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT directive @deprecated( reason: String! = "No longer supported" -) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE | DIRECTIVE_DEFINITION directive @specifiedBy(url: String!) on SCALAR @@ -33,7 +33,7 @@ type __Schema { queryType: __Type! mutationType: __Type subscriptionType: __Type - directives: [__Directive!]! + directives(includeDeprecated: Boolean! = false): [__Directive!]! } type __Type { @@ -92,6 +92,8 @@ type __Directive { isRepeatable: Boolean! locations: [__DirectiveLocation!]! args(includeDeprecated: Boolean! = false): [__InputValue!]! + isDeprecated: Boolean! + deprecationReason: String } enum __DirectiveLocation { @@ -114,5 +116,6 @@ enum __DirectiveLocation { ENUM_VALUE INPUT_OBJECT INPUT_FIELD_DEFINITION + DIRECTIVE_DEFINITION } ``` diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 44760852c..00216acea 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -40,6 +40,7 @@ TypeSystemExtension : - SchemaExtension - TypeExtension +- DirectiveExtension Type system extensions are used to represent a GraphQL type system which has been extended from some previous type system. For example, this might be used by @@ -2033,7 +2034,7 @@ Following are examples of result coercion with various types and values: ## Directives DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? -`repeatable`? on DirectiveLocations +Directives[Const]? `repeatable`? on DirectiveLocations DirectiveLocations : @@ -2069,6 +2070,7 @@ TypeSystemDirectiveLocation : one of - `ENUM_VALUE` - `INPUT_OBJECT` - `INPUT_FIELD_DEFINITION` +- `DIRECTIVE_DEFINITION` 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 @@ -2242,13 +2244,13 @@ condition is false. ```graphql directive @deprecated( reason: String! = "No longer supported" -) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE | DIRECTIVE_DEFINITION ``` 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, arguments on a field, input fields on an input -type, or values of an enum type. +type, values of an enum type, or directives. Deprecations include a reason for why it is deprecated, which is formatted using Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). @@ -2321,3 +2323,24 @@ input UserUniqueCondition @oneOf { organizationAndEmail: OrganizationAndEmailInput } ``` + +### Directive Extensions + +DirectiveExtension : extend directive @ Name Directives[Const] + +Directive extensions are used to represent a directive which has been extended +from some previous directive. For example, this might be used by a GraphQL tool +or service which adds directives to an existing directive. + +**Type Validation** + +Directive extensions have the potential to be invalid if incorrectly defined. + +1. The previous directive must already be defined. +2. Any non-repeatable directives provided must not already apply to the previous + directive. +3. Any directives provided must not contain the use of a Directive which + references the previous directive directly. +4. Any directives provided must not contain the use of a Directive which + references the previous directive indirectly by referencing a Type or + Directive which transitively includes a reference to the previous Directive. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 8963a3e9c..2138e7e70 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -138,7 +138,7 @@ type __Schema { queryType: __Type! mutationType: __Type subscriptionType: __Type - directives: [__Directive!]! + directives(includeDeprecated: Boolean! = false): [__Directive!]! } type __Type { @@ -205,6 +205,8 @@ type __Directive { isRepeatable: Boolean! locations: [__DirectiveLocation!]! args(includeDeprecated: Boolean! = false): [__InputValue!]! + isDeprecated: Boolean! + deprecationReason: String } enum __DirectiveLocation { @@ -227,6 +229,7 @@ enum __DirectiveLocation { ENUM_VALUE INPUT_OBJECT INPUT_FIELD_DEFINITION + DIRECTIVE_DEFINITION } ``` @@ -248,6 +251,8 @@ Fields\: must be included in this set. - `directives` must return the set of all directives available within this schema including all built-in directives. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated directives are also returned. ### The \_\_Type Type @@ -499,6 +504,7 @@ supported. All possible locations are listed in the `__DirectiveLocation` enum: - {"ENUM_VALUE"} - {"INPUT_OBJECT"} - {"INPUT_FIELD_DEFINITION"} +- {"DIRECTIVE_DEFINITION"} Fields\: @@ -512,3 +518,7 @@ Fields\: {true}, deprecated arguments are also returned. - `isRepeatable` must return a Boolean that indicates if the directive may be used repeatedly at a single location. +- `isDeprecated` returns {true} if this directive should no longer be used, + otherwise {false}. +- `deprecationReason` returns the reason why this directive is deprecated, or + null if this directive is not deprecated.