Add support for directives on directive definitions

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
 

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
 }
 ```

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.

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.