Here's your chance to speak at GraphQL Summit in New York City, October 8 - 10, 2024! 🏙️ Submit your proposal by May 31.
Launch GraphOS Studio
Apollo Server 3 is officially deprecated, with end-of-life scheduled for 22 October 2024. Learn more about upgrading to a supported Apollo Server version.

Creating schema directives

Apply custom logic to GraphQL types, fields, and arguments

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

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

# Definition
directive @uppercase on FIELD_DEFINITION
type Query {
# Usage
hello: String @uppercase

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


A directive definition looks like this:

directive @deprecated(
reason: String = "No longer supported"
  • This is the definition for the @deprecated directive in the GraphQL spec.
  • The directive takes one optional (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 . Your directive can support any combination of these locations.

Name /


The definition of a custom scalar



The definition of an object type



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



The definition of a field argument



The definition of an interface



The definition of a union



The definition of an enum



The definition of one value within an enum



The definition of an input type



The definition of a field within an input type



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


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:

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 queries sent from the client, implementing 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 GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy