Custom Type System Directives

Directives That Actually Enforce Something

Every GraphQL developer has used the built-in directives: @skip and @include change what gets selected, @deprecated annotates a field. All three are interpreted by the executor itself, which is why they work everywhere without configuration.

Custom directives extend the same syntax to rules the schema cares about but the specification does not:

directive @auth(requires: Role = USER!) on FIELD_DEFINITION | OBJECT
directive @rateLimit(max: Int!, window: String!) on FIELD_DEFINITION
directive @constraint(minInt: Int, maxInt: Int) on INPUT_FIELD_DEFINITION
directive @sql(column: String!) on FIELD_DEFINITION

Three parts of that block do real work:

• The locations list is a permission list. on FIELD_DEFINITION | OBJECT allows the directive on a field or a whole type and nothing else. Put @auth on an operation type and validation fails with "Directive @auth may not be used on QUERY" — the mistake is caught when the schema builds, not in review three days later.
• Arguments are typed. max: Int! means @rateLimit(max: "five") fails validation exactly like a bad field argument does, before anything runs.
• The name is the contract. Tooling, code generators, and other teams read these names; renaming a directive that appears across modules is a schema change like any other.

What they are for

The payoff is one declaration both humans and machines read:

type Query {
  "Anyone signed in."
  me: User @auth(requires: USER)

  "Admins only."
  auditLog(range: DateRange!): [AuditEntry!]! @auth(requires: ADMIN)
}

Without directives, those two rules live in middleware, resolver wrappers, and a wiki page — three places that drift apart until the wiki and the code disagree about who can read the audit log. With them, an introspection query answers "which fields require admin?" in one round trip, and a reviewer sees the requirement next to the field it protects.

Directives also read well in generated documentation, which changes review behavior: reviewers debate the rule itself instead of hunting through middleware to discover the rule exists.

The catch is one sentence long: declaring a rule and enforcing it are different steps. That gap is the subject of the next chapter.

Where a Directive May Appear, and Where It Runs

A directive in SDL is metadata. Unless something on the server executes it, @auth guarantees nothing — introspection will cheerfully report the rule while every resolver stays open. Server frameworks provide a schema transformation hook that wraps resolvers at startup:

const { mapSchema, getDirective, MapperKind } = require('@graphql-tools/utils');
const { defaultFieldResolver, GraphQLError } = require('graphql');

function authDirectiveTransformer(schema) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const matches = getDirective(schema, fieldConfig, 'auth');
      if (!matches || matches.length === 0) return fieldConfig;

      const { requires } = matches[0].args;
      const { resolve = defaultFieldResolver } = fieldConfig;

      return {
        ...fieldConfig,
        resolve: (root, args, ctx, info) => {
          if (!ctx.role || !hasRole(ctx.role, requires)) {
            throw new GraphQLError('FORBIDDEN', {
              extensions: { code: 'FORBIDDEN', required: requires },
            });
          }
          return resolve(root, args, ctx, info);
        },
      };
    },
  });
}

export const schema = authDirectiveTransformer(makeExecutableSchema({ typeDefs, resolvers }));

Read the shape: the transformer walks fields, finds the directive, and replaces resolve with a wrapper that checks ctx.role before delegating to the original. Field-level directives wrap one field; an OBJECT-level directive must be applied to each of that type's fields, which is why object-wide auth is a second loop in most implementations rather than a one-line reuse.

Placement decides the layer

Order matters when directives stack. @auth then @rateLimit should check the role before spending rate budget, so compose the wrappers outermost-first in that order — an inverted stack spends a paid rate slot on a request that was always going to be rejected.

Two cautions from production. Directive execution happens in the GraphQL layer, so anything reaching the resolver without passing through it — an internal job runner, a direct function call — gets no protection; keep an authorization check in the service as defense in depth. And building the schema with transformers must happen once at startup, not per request, or you pay a schema walk on every operation.

Directive-Driven Tooling and the Decorations Trap

Directives earn their keep twice: once when a server executes them, and once when tooling merely reads them.

type Product {
  id: ID!
  "Maps to products.sku in the warehouse database."
  sku: String! @sql(column: "sku")
  price: Money! @auth(requires: SUPPORT)
  createdAt: DateTime! @timestamp(mode: CREATED_AT)
}

A code generator walks those annotations and emits what would otherwise be handwritten: an ORM mapping from @sql, a typed authorization hook from @auth, a client-side formatter from @timestamp. Federation's @key(fields: "id") is the same idea at scale — a directive whose only consumer is the composition engine — and @external, @shareable, and friends do the work of a paragraph of documentation each. Docs sites read @example to render samples without maintaining a second source of truth.

The trap

A schema full of @auth and @constraint looks locked down. If no transformer executes them, it is decoration: the rule shows up in introspection, the review approves it, and the resolver still runs unguarded — an attacker reading the schema learns exactly which rules are imaginary. Two habits prevent it:

1. Every custom directive gets an owner and a test. The test asserts that a request violating the rule is rejected — not that the directive appears in SDL. Presence is easy to verify and proves nothing.
2. Limit the vocabulary. Five directives that all run beat twenty that only describe, because each new directive is API surface: renaming it or changing its arguments affects every module that imports its definition.

Repeatable and composed directives

A directive declared repeatable may stack on one element (@tag(name: "public") @tag(name: "beta")), which is useful for labels but means order and duplicates become meaningful. Directive definitions must be unique: declaring @auth in two composed modules with different argument types fails composition outright rather than picking a winner — exactly the collision case schema composition guidelines exists to catch before merge.

Interview framing: name the two halves — declaration with locations, execution via a schema transformer — give one example of tooling that reads a directive without executing it, and say why a decorative directive is worse than having none at all.