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

[glen-84]

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:

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).

[martinbonnin]

Question: is section 5. exclusively about executable documents? 5.1.1. is about execution. But it could be argued that the other ones apply the same whether the document is an executable document or any other document?

[glen-84]

They all seem request/execution-oriented, from what I can see.

[martinbonnin]

That's surely what the context is but if you read for an example the Values validation:

    For each literal Input Value value in the document:
        Let type be the type expected in the position value is found.
        value must be coercible to type (with the assumption that any variableUsage nested within value will represent a runtime value valid for usage in its position).

Nowhere it's said that the document is an executable document. It's only said in 5.1.1. but I'd argue that the subsection does not necessarily apply to parent sections. I read 5.1.1. as "if the document is to be executed, then it must not have type system definitions". Agree it could be made more explicit though (if that's what it really is)

[benjie]

From the section 5 intro:

A GraphQL service does not just verify if a request is syntactically correct, but also ensures that it is unambiguous and mistake-free in the context of a given GraphQL schema.

An invalid request is still technically executable [...]

Typically validation is performed in the context of a request immediately before execution, [...]

Section 5 is about validating requests, specifically the document included in a request. 5.1.1 makes this even clearer by making sure the document being validated only contains executable definitions, since a request must not include type system definitions.

Section 6.1.1 goes on to further state:

As explained in the Validation section, only requests which pass all validation rules should be executed. [...] Typically validation is performed in the context of a request immediately before execution [...]

[benjie]

@glen-84 I don't think the spec cares too much about SDL as input¹ in general. It's more of a "nice to have" than something strictly specified - there are grammar rules (e.g. a TypeSystemDocument cannot contain type extensions (extend *)) but not much in the way of validation. The schema itself has validation, but the schema does not have a concept of "applied directives" (deprecated / specifiedBy / oneOf become their own thing in the schema - no longer directives) - it's expected that tooling will take the directives and apply changes to the schema with them. If I'm not mistaken, solving this issue that you've raised would actually require resolving a much larger omission - validation of type system SDL (potentially with or without type extensions) - so I think its presence in prose is about as good as it'll get until we have something like that.

Footnotes

1. The specification mostly focuses on SDL as output - as a way of presenting a schema via text: "when representing a GraphQL schema using the type system definition language, a schema definition should be omitted if each root operation type uses its respective default root type name, no other type uses any default root type name, and the schema does not have a description." / "Schema extensions are used to represent a schema which has been extended from a previous schema." ↩

[yaacovCR]

solving this issue that you've raised would actually require resolving a much larger omission - validation of type system SDL (potentially with or without type extensions)

Fortuitous timing?

graphql/graphql-js#4835