Launch Apollo Studio

Creating schema directives

Apply custom logic to GraphQL types, fields, and arguments


Before you create a custom schema directive, learn the basics about directives.

Your schema can define custom directives that can then decorate other parts of your schema:

schema.graphql
# Definition
directive @uppercase on FIELD_DEFINITION

type Query {
  # Usage
  hello: String @uppercase
}

See an example implementation of this directive on CodeSandbox:

Edit upper-case-directive

When you start up your app, you can use directives to transform your executable schema's behavior before you provide that schema to Apollo Server. For example, you can modify the resolver function for any decorated field (for the schema above, it could transform the hello resolver's original result to uppercase).

Defining

A directive definition looks like this:

schema.graphql
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE
  • This is the definition for the @deprecated directive in the GraphQL spec.
  • The directive takes one optional argument (reason) with a default value ("No longer supported").
  • The directive can decorate any number of FIELD_DEFINITIONs and ENUM_VALUEs in your schema.

Supported locations

Your custom directive can appear only in the schema locations you list after the on keyword in the directive's definition.

The table below lists all available locations in a GraphQL schema. Your directive can support any combination of these locations.

Name /
MapperKind
Description
SCALAR

SCALAR_TYPE

The definition of a custom scalar

OBJECT

OBJECT_TYPE

The definition of an object type

FIELD_DEFINITION

OBJECT_FIELD

The definition of a field within any defined type except an input type (see INPUT_FIELD_DEFINITION)

ARGUMENT_DEFINITION

ARGUMENT

The definition of a field argument

INTERFACE

INTERFACE_TYPE

The definition of an interface

UNION

UNION_TYPE

The definition of a union

ENUM

ENUM_TYPE

The definition of an enum

ENUM_VALUE

ENUM_VALUE

The definition of one value within an enum

INPUT_OBJECT

INPUT_OBJECT_TYPE

The definition of an input type

INPUT_FIELD_DEFINITION

INPUT_OBJECT_FIELD

The definition of a field within an input type

SCHEMA

ROOT_OBJECT

The top-level schema object declaration with query, mutation, and/or subscription fields (this declaration is usually omitted)

Implementing

Important: Apollo Server 3 does not provide built-in support for custom directives. To enable this support, you need to install certain @graphql-tools libraries.

This article uses @graphql-tools version 8. Previous versions use a different API for custom directives. If you're using an earlier version of @graphql-tools, see the Apollo Server v2 docs.

After you define your directive and its valid locations, you still need to define the logic that Apollo Server executes whenever it encounters the directive in your schema.

To define custom directive logic with @graphql-tools v8 and later, you can create transformer functions that transform an executable schema's behavior based on the directives that are present in it.

1. Install required libraries

First, install the following @graphql-tools libraries:

npm install @graphql-tools/schema @graphql-tools/utils

2. Define directive logic

To define what Apollo Server does when it encounters your directive, you can create a transformer function. This function uses the mapSchema function to iterate through locations in your schema (field definitions, type definitions, etc.) and perform transformations wherever it encounters a particular directive (or set of directives).

For example, here's a possible transformer function for the default @deprecated directive:

directives.js
const { mapSchema, getDirective, MapperKind } = require('@graphql-tools/utils');

function deprecatedDirectiveTransformer(schema, directiveName) {
  return  mapSchema(schema, {

    // Executes once for each object field definition in the schema
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const deprecatedDirective = getDirective(schema, fieldConfig, directiveName)?.[0];
      if (deprecatedDirective) {
        fieldConfig.deprecationReason = deprecatedDirective['reason'];
        return fieldConfig;
      }
    },

    // Executes once for each enum value definition in the schema
    [MapperKind.ENUM_VALUE]: (enumValueConfig) => {
      const deprecatedDirective = getDirective(schema, enumValueConfig, directiveName)?.[0];
      if (deprecatedDirective) {
        enumValueConfig.deprecationReason = deprecatedDirective['reason'];
        return enumValueConfig;
      }
    }
  });
};

As shown, the second parameter you pass mapSchema is an object with keys that represent one or more locations in your schema. The MapperKind enum value for each supported location is listed in the table above.

Example: Uppercasing strings

Suppose you want to convert certain String fields in your schema to uppercase before they're returned.

This example defines an @uppercase directive for this purpose:

This code replaces the resolver of an @uppercase field with a new function. This new function first calls the original resolver, then transforms its result to uppercase (assuming it's a string) before returning it.

Additional examples

For additional examples of transforming executable schemas with directives and mapSchema, see the @graphql-tools docs.

What about query directives?

Although directive syntax can also appear in GraphQL queries sent from the client, implementing query directives requires runtime transformation of query documents. We have deliberately restricted this implementation to transformations that take place at server construction time.

We believe confining this logic to your schema is more sustainable than burdening your clients with it, though you can probably imagine a similar sort of abstraction for implementing query directives. If that possibility becomes a need for you, let us know.

Edit on GitHub