graphql / graphql/graphql-spec

Type-system directive placement is not formalized as a validation rule

Open
#1,233 6 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.