In a GraphQL schema, what can an authorization directive on a field decide, and what must a resolver still check?

## What a directive is, and what it is not A directive is an annotation attached to a location in a document or a schema. The specification defines the syntax for declaring one and the set of locations it may appear on, and it defines the behaviour of a handful of built-in ones. For anything a team declares itself, **the specification defines no behaviour at all** — the server chooses what to do when it sees the annotation. So an access-control directive is a convention, not a feature of GraphQL, and two servers given the same annotated schema may do entirely different things with it, or nothing. That matters in an interview because candidates often describe such a directive as though the language enforces it. It does not. A schema is data; something in the server has to read the annotation and wrap or gate the field's resolution. ## The static half of the decision Authorization decisions split cleanly in two. The **static** half depends only on the caller: does this viewer hold the `dispatcher` role, the `rates:read` scope, the internal-employee claim? That question can be answered from the request context without touching any data, which is exactly why it can be attached to the field declaration once and enforced everywhere the field is selected. ```graphql directive @requiresScope(scope: String!) on FIELD_DEFINITION | OBJECT type Shipment { id: ID! status: ShipmentStatus! rateAgreement: RateAgreement @requiresScope(scope: "rates:read") driverPhone: String @requiresScope(scope: "pii:read") } ``` The payoff is not that this is less code than an `if`. It is that the rule now lives in an artefact you can *scan*. A four-person platform team maintaining a schema that thirty-one product teams extend cannot read every resolver, but it can run a check over the schema and list every field of a sensitive type carrying no annotation. Declarative rules turn an authorization audit into a query over the schema. ## The instance half, which a directive cannot reach The other half depends on the object: is this viewer's account the shipper on *this* consignment, is this carrier the one that actually hauled *this* leg, has the customer's access to this shipment already been revoked? A static annotation on the field declaration has none of that in hand. It knows the viewer and the field; it does not know which shipment is about to be returned, and a scope check will happily let a dispatcher with `rates:read` read the negotiated rate of a shipment belonging to a competitor. So the honest description is a two-layer model: the directive answers *may this kind of caller ever read this kind of field*, and something closer to the data answers *may this caller read this row*. A candidate who claims the directive alone is sufficient has not thought about multi-tenancy. ## Where a directive-based scheme leaks Three failure modes recur. **Placement drift.** The annotation is attached where it was declared. Annotate `Shipment.rateAgreement`, and a new field `Leg.rateAgreement` added by another team six months later is unguarded. Annotating the *type* rather than every field that returns it is stronger, if the server supports applying the rule at that location. **Silent no-ops.** Because behaviour is server-defined, an annotation the server does not wire up is decoration. This is genuinely dangerous: the schema reads as though the field is protected, review passes, and nothing enforces it. The mitigation is a test that asserts a denial for each declared rule — not a test that the annotation is present. **Composition with arguments.** A field-level rule says nothing about the arguments the field was given. `shipments(accountId: ID!)` gated by a scope is still a cross-tenant read if the resolver trusts `accountId`. ## Choosing between the two placements Use a declared rule when the policy is coarse, stable and worth making visible: PII fields, financial fields, internal-only fields. Use a resolver or data-layer check when the policy depends on the record. Prefer to keep the *static* rule declared even when an instance check also exists, because the declaration is what makes coverage measurable — a field with an instance check buried in code looks identical, from outside, to a field with no check at all. One more practical note: whatever the mechanism, decide what a denial *looks like* — an error at the field's path, a null, an omitted list entry — and make it consistent across both layers, because a schema where the declarative layer errors and the data layer silently filters gives two different signals for the same policy.