Directive Definitions

A directive definition is a declaration of **shape and placement**. It says what the directive is called, what arguments it accepts, whether it may appear more than once in the same spot, and — crucially — exactly which positions in the grammar it is allowed to appear at. It says nothing whatsoever about behaviour. ## The five parts ```graphql "Marks a numeric field as carrying a physical unit." directive @sensorUnit( symbol: String! precision: Int = 2 ) on FIELD_DEFINITION | SCALAR ``` Reading that top to bottom: 1. **A description** (optional). A string or block string immediately before the `directive` keyword. It is documentation, and introspection returns it. 2. **The name** (required), always written with a leading `@`. Directive names are their own namespace — introspection returns them in a `directives` list separate from `types`, so a directive called `@sensorUnit` does not collide with a type called `SensorUnit`. Two directives in one schema may not share a name. 3. **An argument list** (optional). Omit the parentheses entirely when the directive takes no arguments. 4. **The `repeatable` keyword** (optional), which sits between the argument list and `on`. 5. **The `on` clause** (required). A `|`-separated list of location names. A leading `|` is allowed, which is convenient when the list is long enough to wrap. ## Arguments follow the field-argument rules exactly A directive argument is declared like any other argument in the schema: a name, a type, and an optional default value. The type must be an **input type** — a scalar, an enum, an input object, or a list/Non-Null wrapper around one of those. An output object type, an interface or a union is a schema validity error. Arguments are named, never positional, so applications may supply them in any order and may omit any argument that is nullable or has a default. There is one rule specific to directives that is easy to trip over: a directive definition must not reference itself, directly or indirectly, through the types and default values in its own argument list. A directive whose argument is an input object that is itself annotated with that same directive is invalid, because the server would have no order in which to resolve it. ## `repeatable` and the uniqueness rule Without `repeatable`, a directive may appear **at most once at any given location**. Applying it twice to the same field definition is a validation error. Adding the keyword lifts that restriction, and every consumer of the directive must then read a *list* of applications rather than a single one. Introspection reports the flag as `isRepeatable` on the directive's entry. ## What the definition deliberately does not say Nothing in a directive definition describes what happens when the directive is applied. The specification assigns behaviour only to the handful of directives it defines itself; for anything you declare, the definition is a contract about where the annotation may be written and what data it carries, and something outside the schema language has to act on it. That is why a schema can be perfectly valid while a custom directive does nothing at all. ## The built-ins are already declared Every schema comes with the specification's own directives pre-declared: `@skip` and `@include` at executable locations, and `@deprecated` and `@specifiedBy` at type-system locations. You do not write definitions for them, and redeclaring one of those names is an error. ## A worked example A farm sensor graph tracks soil probes across paddocks. The schema author wants units and free-text audit annotations to travel with the schema: ```graphql directive @sensorUnit(symbol: String!, precision: Int = 2) on FIELD_DEFINITION directive @auditNote(text: String!) repeatable on OBJECT | FIELD_DEFINITION type SoilProbe @auditNote(text: "Field set frozen 2026-04-11") { id: ID! moisturePercent: Float! @sensorUnit(symbol: "%") batteryMillivolts: Int! @sensorUnit(symbol: "mV", precision: 0) } ``` `@sensorUnit` is not repeatable, so a second `@sensorUnit` on `moisturePercent` fails validation. `@auditNote` is, so `SoilProbe` may accumulate as many notes as the team writes. Applying `@sensorUnit` to `SoilProbe` itself fails too, because `OBJECT` is not in its `on` clause — and that failure is the entire value of the clause. The location list is the only part of the definition a server is obliged to enforce, and it is what turns an annotation from free-form text into something a schema can be checked against. In an interview, the answer that scores is the one that separates the three concerns cleanly: the **name and arguments** are the data the annotation carries, the **`on` clause** is where it may be written, and the **behaviour** lives somewhere else entirely.