Skip to content

Add support for directives on directive definitions #1206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leebyron merged 7 commits into from
Jun 4, 2026
Merged

Add support for directives on directive definitions #1206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7167aa9
Add support for directives on directives
IvanGoncharov Dec 2, 2021
40fc00a
Change the directive definition syntax to have applied directives aft…
BoD Dec 2, 2025
5595ab3
Add directive extensions
BoD Nov 27, 2025
0ef5222
Make @deprecated applicable to DIRECTIVE_DEFINITION
BoD Nov 27, 2025
d2c5424
Update introspection
BoD Nov 27, 2025
610d8db
Reformat with prettier
BoD Dec 18, 2025
a257894
Directives are not types
BoD Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion spec/Appendix C -- Grammar Summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,7 @@ TypeSystemExtension :

- SchemaExtension
- TypeExtension
- DirectiveExtension

SchemaDefinition : Description? schema Directives[Const]? {
RootOperationTypeDefinition+ }
Expand Down Expand Up @@ -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 :

Expand Down Expand Up @@ -413,6 +416,7 @@ TypeSystemDirectiveLocation : one of
- `ENUM_VALUE`
- `INPUT_OBJECT`
- `INPUT_FIELD_DEFINITION`
- `DIRECTIVE_DEFINITION`

## Schema Coordinate Syntax

Expand Down
7 changes: 5 additions & 2 deletions spec/Appendix D -- Specified Definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -33,7 +33,7 @@ type __Schema {
queryType: __Type!
mutationType: __Type
subscriptionType: __Type
directives: [__Directive!]!
directives(includeDeprecated: Boolean! = false): [__Directive!]!

@benjie benjie May 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm hesitant to add this, since I think the whole includeDeprecated dance was a mistake. I think I'd rather see the includeDeprecated argument be itself deprecated across the board, but it defaulting to = false makes this challenging.

@BoD BoD Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I certainly agree about includeDeprecated's benefits being outweighed by its drawbacks. Having it here was about consistency - but maybe if we're planning on deprecating it, we can start by not having it here! Let's discuss this at the next WG.

}

type __Type {
Expand Down Expand Up @@ -92,6 +92,8 @@ type __Directive {
isRepeatable: Boolean!
locations: [__DirectiveLocation!]!
args(includeDeprecated: Boolean! = false): [__InputValue!]!
isDeprecated: Boolean!
deprecationReason: String
}

enum __DirectiveLocation {
Expand All @@ -114,5 +116,6 @@ enum __DirectiveLocation {
ENUM_VALUE
INPUT_OBJECT
INPUT_FIELD_DEFINITION
DIRECTIVE_DEFINITION
}
```
29 changes: 26 additions & 3 deletions spec/Section 3 -- Type System.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 :

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/)).
Expand Down Expand Up @@ -2321,3 +2323,24 @@ input UserUniqueCondition @oneOf {
organizationAndEmail: OrganizationAndEmailInput
}
```

### Directive Extensions

DirectiveExtension : extend directive @ Name Directives[Const]

@mjmahone mjmahone May 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is interesting: should we be able to extend a directive with new arguments? We can extend a type with new fields that themselves have new arguments.

There is even a special Schema Coordinate for directive arguments.

@BoD BoD May 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question!

In my opinion, I think yes it would probably make sense in principle to have that ability, even if for consistency alone.
That being said, I would rather tackle this in a separate change later, and based on demand for it.

Curious to know what others think!

@mjmahone mjmahone May 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it would be controversial, but it does make sense to stack into two PRs to make discussion specifically about argument extension more focused.

@martinbonnin martinbonnin May 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mjmahone Am I correct that https://gaps.graphql.org/GAP-33/draft/ would also solve this use case?

@mjmahone mjmahone Jun 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well, GAP-33 assumes that this is already available.

But I think I should iterate on that GAP to make inner extensions use a different syntax because as-is it's not good!


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
Comment thread
yaacovCR marked this conversation as resolved.
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.
12 changes: 11 additions & 1 deletion spec/Section 4 -- Introspection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ type __Schema {
queryType: __Type!
mutationType: __Type
subscriptionType: __Type
directives: [__Directive!]!
directives(includeDeprecated: Boolean! = false): [__Directive!]!
}

type __Type {
Expand Down Expand Up @@ -205,6 +205,8 @@ type __Directive {
isRepeatable: Boolean!
locations: [__DirectiveLocation!]!
args(includeDeprecated: Boolean! = false): [__InputValue!]!
isDeprecated: Boolean!
deprecationReason: String
}

enum __DirectiveLocation {
Expand All @@ -227,6 +229,7 @@ enum __DirectiveLocation {
ENUM_VALUE
INPUT_OBJECT
INPUT_FIELD_DEFINITION
DIRECTIVE_DEFINITION
}
```

Expand All @@ -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

Expand Down Expand Up @@ -499,6 +504,7 @@ supported. All possible locations are listed in the `__DirectiveLocation` enum:
- {"ENUM_VALUE"}
- {"INPUT_OBJECT"}
- {"INPUT_FIELD_DEFINITION"}
- {"DIRECTIVE_DEFINITION"}

Fields\:

Expand All @@ -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.