Launch GraphOS Studio
Apollo Server 2 is officially end-of-life as of 22 October 2023. Learn more about upgrading.


Configure GraphQL types, fields, and arguments

A directive decorates part of a or with additional configuration. Tools like (and

) can read a 's and perform custom logic as appropriate.

are preceded by the @ character, like so:

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

This example shows the @deprecated , which is a

(i.e., it's part of the
GraphQL specification
). It demonstrates the following about directives:

  • Directives can take of their own (reason in this case).
  • Directives appear after the declaration of what they decorate (the oldField 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 either a schema FIELD_DEFINITION (as shown at the top of the article) or a schema ENUM_VALUE definition (as shown here):

enum MyEnum {
OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.")

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

If you

, 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 or exclusively in GraphQL (rarely both, although the spec allows this).

For example, among the

, @deprecated is a schema-exclusive directive and @skip and @include are operation-exclusive directives.


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

Default directives


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.

Custom schema directives

You can extend Apollo Server with custom schema directives created by you or a third party.

To learn how to create custom directives, see


To use a custom directive:

  1. Make sure the directive is defined in your schema with all valid locations listed.

  2. If the directive uses a SchemaDirectiveVisitor subclass to perform custom logic, provide it to the ApolloServer constructor via the schemaDirectives object.

    The schemaDirectives object maps the name of a directive (e.g., upper) to the subclass that implements its behavior (e.g., UpperCaseDirective).

The following example defines an UpperCaseDirective subclass for use with the @upper custom directive. Because it's decorated with @upper, the Query.hello field returns HELLO WORLD! instead of Hello world!.

const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server');
const { defaultFieldResolver } = require('graphql');
// Subclass definition for @upper directive logic
class UpperCaseDirective extends SchemaDirectiveVisitor {
visitFieldDefinition(field) {
const { resolve = defaultFieldResolver } = field;
field.resolve = async function (...args) {
const result = await resolve.apply(this, args);
if (typeof result === 'string') {
return result.toUpperCase();
return result;
// Schema definition (including custom directive)
const typeDefs = gql`
directive @upper on FIELD_DEFINITION
type Query {
hello: String @upper
// Resolvers
const resolvers = {
Query: {
hello: (parent, args, context) => {
return 'Hello world!';
// Add directive to the ApolloServer constructor
const server = new ApolloServer({
schemaDirectives: {
upper: UpperCaseDirective,
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`)
Custom scalars
Creating directives
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy