Directive Introspection Behavior Across GraphQL Spec Versions

Directive introspection behavior across GraphQL spec versions

Answer: Before the June 2018 GraphQL release the specification did not define a __schema.directives field, so exposing directive definitions was optional and implementation‑dependent. Starting with the 2018‑06 spec, __schema.directives is required and must list every directive—built‑in (@skip, @include, @deprecated) and any custom directives—each with name, description, locations, and argument definitions when introspection is enabled.

Confirmed facts

• Pre‑2018‑06: no mandate; servers may include or omit __schema.directives.
• Post‑2018‑06: __schema.directives must be present and non‑empty for schemas that define directives.
• The spec places no explicit depth or size limits on the introspection response; large directive sets can increase payload size and memory usage.

Likely explanation for earlier variability

Because the early spec left the field undefined, some servers chose to expose directives for debugging tools, while others omitted them to keep introspection payloads small or to avoid leaking schema details. This explains the mixed behavior you may observe in older implementations.

Steps to verify your server’s behavior

1. Run an introspection query requesting the directives list, e.g.:

{
  __schema {
    directives {
      name
      description
      locations
      args {
        name
        type {
          kind
          name
          ofType { kind name }
        }
      }
    }
  }
}

1. Check the response:

• If the __schema.directives array is absent or empty and the server claims compliance with a spec version < 2018-06, this matches the optional behavior.
• If the array contains entries for @skip, @include, @deprecated and any custom directives you have defined, and the server claims spec >= 2018-06, the behavior conforms to the mandatory requirement.

To determine which path applies, please confirm the GraphQL spec version your server claims to implement (e.g., via documentation, response headers, or server version).