Mark deprecated fields or enum values with @deprecated.
Schema governance
GraphQL · Class
GraphQLDirective
GraphQL directives use an @-prefixed name to annotate schemas or operations. They can influence validation or execution and may define arguments plus permitted locations.
How it works
A GraphQL directive is schema or operation metadata written with an @ name. Type-system directives annotate schema elements so validation or execution can treat them differently, while executable directives let operations influence query execution.
Syntax
directive @name(arguments) on LOCATIONKey points
- Directives provide a reusable way to alter how selected schema parts or operations are handled.
- Schema directives can attach metadata to types, fields, and arguments.
- Executable directives are intended for use inside GraphQL operations.
- GraphQL includes standardized directives in addition to application-defined directives.
- Implementations supporting SDL provide @deprecated for marking deprecated schema elements.
- The shown @deprecated declaration permits use on fields and enum values.
Common mistakes
- A directive can only be applied at locations declared in its definition, such as FIELD_DEFINITION or ENUM_VALUE.
- Directive arguments may have defaults, so callers may omit an argument when the declaration supplies one.
Example: Schema directive for authorization
directive @auth(rule: Rule) on FIELD_DEFINITION
enum Rule {
IS_AUTHOR
}
type Post {
authorId: ID!
body: String @auth(rule: IS_AUTHOR)
}This SDL declares an authorization directive, restricts it to field definitions, and applies it to the Post.body field.
When to use it
Annotate fields with directives such as authorization metadata.
Cross-cutting schema behavior
Use executable directives to control whether selected fields are included during execution.
Conditional query results
Interview questions
QWhat is a GraphQL directive?
Directives add metadata or behavior using an @-prefixed name. Type-system directives annotate types, fields, or arguments; executable directives can be used in operations and affect execution.
Follow-up: How would you limit a directive to schema fields? Define it with FIELD_DEFINITION as its allowed location.
QWhat does a directive definition specify?
A directive definition declares its name, arguments, and permitted locations. For example, @deprecated accepts an optional String reason and can target FIELD_DEFINITION or ENUM_VALUE.
Follow-up: What happens when reason is omitted for @deprecated? Its default text is used: No longer supported.
QHow does the documentation illustrate a built-in directive?
The built-in @deprecated directive marks schema elements as deprecated. Its nullable reason argument has type String and a default value of No longer supported.
Follow-up: Can the same directive be used anywhere? No; each use must match one of the locations declared by its definition.
Related
@deprecated@include@skiptype system directivesexecutable directivesFIELD_DEFINITIONENUM_VALUE