3.2.11: @deprecated directive now appears in DIRECTIVE_DEFINITION locations, breaking GraphQL codegen tools

[jamessingizi]

Summary

The 3.2.11 release added support for directives on directive definitions ("Add support for directives on directive definitions"). As a side-effect, the @deprecated built-in directive now includes DIRECTIVE_DEFINITION in its reported locations when queried via __schema introspection.

Steps to reproduce

Run an introspection query against any server using graphql-core 3.2.11:

curl -s 'https://your-server/graphql' \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { directives { name locations } } }"}' | python3 -m json.tool

You will see the @deprecated directive now includes DIRECTIVE_DEFINITION in its locations:

{
    "name": "deprecated",
    "locations": [
        "FIELD_DEFINITION",
        "ARGUMENT_DEFINITION",
        "INPUT_FIELD_DEFINITION",
        "ENUM_VALUE",
        "DIRECTIVE_DEFINITION"
    ]
}

Impact

This breaks GraphQL codegen tools (e.g. @graphql-codegen/cli / yarn codegen) that do not expect DIRECTIVE_DEFINITION as a valid location for @deprecated. These tools fail with an error when they encounter this unexpected location in the introspection result.

The GraphQL June 2018 spec and the current stable (October 2021) spec do not include DIRECTIVE_DEFINITION as a valid location for @deprecated. This change therefore introduces a spec-incompatible introspection response that causes real-world tooling breakage.

Expected behaviour

@deprecated should only report locations that are included in the spec it claims to implement (June2018/October2021). DIRECTIVE_DEFINITION should not be listed unless the schema explicitly declares it.

Workaround

Pin graphql-core<3.2.11.

Environment

• graphql-core: 3.2.11
• Python: 3.11+
• Codegen tool: @graphql-codegen/cli (yarn codegen)

[Cito]

Hi @jamessingizi, thanks for the detailed report.

This change is intentional, though, and not specific to graphql-core. As the Python port of graphql-js, graphql-core 3.2.11 corresponds to graphql-js v16.14, which added DIRECTIVE_DEFINITION to @deprecated's locations in graphql/graphql-js#4521 . Any server on graphql-js 16.14+ returns the same introspection result.

It implements graphql-spec RFC #1206 (directives on directive definitions). You're right that this isn't in the released October 2021 spec, but the RFC has reached Stage 2 (Draft), and per the GraphQL RFC process such proposals are implemented in the reference implementation ahead of the next spec release.

The actual breakage is that the older graphql-js bundled with your codegen tooling rejects unknown directive locations when building the client schema. The robust fix is to force graphql@^16.14.0 in your JS project (yarn resolutions / npm overrides) rather than pinning graphql-core since the same issue would resurface with any JS backend on graphql-js 16.14+.