In GraphQL, how do a directive's executable locations differ from its type-system locations?

GraphQL has two entirely separate documents in play, and a directive location names a position in one of them. **Executable locations** are positions in the operation document a client sends. **Type-system locations** are positions in the schema the server publishes. The `on` clause of a directive definition lists which of those positions the directive may be written at, and the two families are read by different machinery at different times. ## The executable locations These are the ones a client may type into a request: `QUERY`, `MUTATION`, `SUBSCRIPTION`, `FIELD`, `FRAGMENT_DEFINITION`, `FRAGMENT_SPREAD`, `INLINE_FRAGMENT`, `VARIABLE_DEFINITION`. A directive at one of these locations arrives with every request that uses it, is validated against the schema's directive definitions along with the rest of the document, and is evaluated during execution of that one request. Change the document, and the annotation changes. The specification defines exactly two executable directives, `@skip` and `@include`; everything else at these locations is an extension. ## The type-system locations These are positions in the schema itself: `SCHEMA`, `SCALAR`, `OBJECT`, `FIELD_DEFINITION`, `ARGUMENT_DEFINITION`, `INTERFACE`, `UNION`, `ENUM`, `ENUM_VALUE`, `INPUT_OBJECT`, `INPUT_FIELD_DEFINITION`. A directive at one of these is written by the schema author, not the caller. It is fixed for every request the schema serves, and a server reads it once, when it builds the executable schema out of the SDL. That is a real operational difference and not just a conceptual one: a type-system annotation costs nothing per request, which matters when the graph is held to something like a 340 ms p99 budget, whereas an executable directive is parsed, validated and evaluated on every single request that carries it. The specification defines two type-system directives, `@deprecated` and `@specifiedBy`. ## The trap: `FIELD` versus `FIELD_DEFINITION` This is the pair interviewers actually probe, because the English word "field" covers both. `FIELD_DEFINITION` is a field **declared** on an object or interface type in the schema — the `moisturePercent: Float!` line. `FIELD` is a field **selected** in an operation document — the `moisturePercent` a client writes inside a selection set. A directive defined `on FIELD_DEFINITION` cannot be written in a query, and a directive defined `on FIELD` cannot be written in the SDL. Both attempts are validation errors, not silently-ignored annotations. The same split shows up elsewhere. `ARGUMENT_DEFINITION` is the declaration of an argument in the schema; there is no executable location for an argument written in a document, because an argument in a document is not a position a directive can attach to. `INPUT_FIELD_DEFINITION` is a field of an input object type in the schema. `SCHEMA` is the schema definition block itself. ## Can one definition list both? Yes — the `on` clause is just a list of location names, and nothing forbids mixing families: ```graphql directive @traceTag(label: String!) on FIELD | FIELD_DEFINITION ``` That is legal, but it is usually a modelling smell: the same name is now read by two different consumers at two different times, one of them per request and one of them at build time, and the code that acts on it has to be written twice. None of the specification's own directives mix families, and a candidate who notices that is showing the right instinct. ## A worked example In a farm sensor graph, the unit a numeric field carries is a property of the schema, and the sample window a caller wants is a property of the request: ```graphql directive @sensorUnit(symbol: String!) on FIELD_DEFINITION directive @sampleAt(isoTimestamp: String!) on FIELD type Paddock { id: ID! moisturePercent: Float! @sensorUnit(symbol: "%") } ``` ```graphql query PaddockMoisture { paddock(id: "PDK-27") { moisturePercent @sampleAt(isoTimestamp: "2026-09-03T04:15:00Z") } } ``` Swap those two annotations and both documents fail validation. That is the whole distinction: the location list is not decoration, it is the mechanism that decides whether an annotation belongs to the contract or to the call. ## Why interviewers care Getting this wrong produces a specific, common design error — reaching for an executable directive to express something that is a permanent property of a field, which pushes the burden onto every caller and makes the property something a client can simply decline to send. The answer that lands is: **type-system directives annotate the contract, executable directives annotate one call**, and the `on` clause is where you commit to which one you meant.