GraphQL Summit is back for three days of insights, hands-on learning, and fun to celebrate the GraphQL community. Join us in San Diego Oct 3-5.
Try Apollo Studio


Configure GraphQL types, fields, and arguments

Looking for Apollo Federation directives? See Federation-specific GraphQL directives.

A directive decorates part of a GraphQL schema or operation with additional configuration. Tools like Apollo Server (and Apollo Client) can read a GraphQL document's directives and perform custom logic as appropriate.

Directives are preceded by the @ character, like so:

type ExampleType {
oldField: String @deprecated(reason: "Use `newField`.")
newField: String

This example shows the @deprecated directive, which is a default directive (i.e., it's part of the GraphQL specification). It demonstrates the following about directives:

  • Directives can take arguments of their own (reason in this case).
  • Directives appear after the declaration of what they decorate (the oldField field in this case)

Valid locations

Each directive can only appear in certain locations within a GraphQL schema or operation. These locations are listed in the directive's definition.

For example, here's the GraphQL spec's definition of the @deprecated directive:

directive @deprecated(
reason: String = "No longer supported"

This indicates that @deprecated can decorate any of the four listed locations. Also note that its reason argument is optional and provides a default value. Usage examples of each location are provided below:

# Note: @deprecated arguments _must_ be optional.
directive @withDeprecatedArgs(
deprecatedArg: String @deprecated(reason: "Use `newArg`"),
newArg: String
) on FIELD
type MyType {
# ARGUMENT_DEFINITION (alternate example on a field's args)
fieldWithDeprecatedArgs(name: String! @deprecated): String
deprecatedField: String @deprecated
enum MyEnum {
OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.")
input SomeInputType {
nonDeprecated: String
deprecated: String @deprecated

If @deprecated appears elsewhere in a GraphQL document, it produces an error.

If you create a custom directive, you need to define it (and its valid locations) in your schema. You don't need to define default directives like @deprecated.

Schema directives vs. operation directives

Usually, a given directive appears exclusively in GraphQL schemas or exclusively in GraphQL operations (rarely both, although the spec allows this).

For example, among the default directives, @deprecated is a schema-exclusive directive and @skip and @include are operation-exclusive directives.

The GraphQL spec lists all possible directive locations. Schema locations are listed under TypeSystemDirectiveLocation, and operation locations are listed under ExecutableDirectiveLocation.

Default directives

The GraphQL specification defines the following default directives:

@deprecated(reason: String)Marks the schema definition of a field or enum value as deprecated with an optional reason.
@skip(if: Boolean!)If true, the decorated field or fragment in an operation is not resolved by the GraphQL server.
@include(if: Boolean!)If false, the decorated field or fragment in an operation is not resolved by the GraphQL server.
Edit on GitHub
Custom scalars
Creating directives