graphql / graphql/graphql-spec
Type-system directive placement is not formalized as a validation rule
- Dominant language
- JavaScript
- Stars
- 14.6k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
The constraint that a directive may only be applied where its declared locations permit is, for the **type system**, stated only as prose in [§3.13 Directives → Custom Directives](https://spec.graphql.org/September2025/#sec-Type-System.Directives.Custom-Directives):
> Directives must only be used in the locations they are declared to belong in.
The only *formal* rule enforcing directive placement, **Directives Are In Valid Locations** (Section 5 — Validation), is scoped to executable documents:
> Type system definitions and extensions are not executable, and are not considered during execution.
That rule therefore covers `ExecutableDirectiveLocation` placement (e.g. `@skip` on a `FIELD`) but not `TypeSystemDirectiveLocation` placement (e.g. a directive applied to a `FIELD_DEFINITION`, `ENUM_VALUE`, or — since #1206 — a `DIRECTIVE_DEFINITION`).
The **Directives → Type Validation** subsection validates a directive *definition* (must include at least one location, must not reference itself, naming, argument rules) but says nothing about validating directive *applications* across the type system.
**Result:** schema-level directive placement is normatively backed only by a single prose sentence, with no formal validation rule, an asymmetry with the executable-document side.
**Question / proposal:** should this be formalized as a type-system validation rule (the SDL analogue of "Directives Are In Valid Locations")? If so, where should it live, a new numbered rule under §3.13 Directives → Type Validation, or a dedicated schema-validation rule covering all type-system directive applications? This became more concretely relevant with the addition of the `DIRECTIVE_DEFINITION` location in #1206.
_Drafted by Claude (Anthropic AI assistant)._
Contributor guide
Assessment
This issue has not been assessed yet.