What does GraphQL's @specifiedBy directive attach to a custom scalar, and who reads it?

## The gap it fills A custom scalar declaration is a name and nothing else. `scalar GeoPoint` tells a reader — human or machine — that values of this type exist and are leaves. It says nothing about whether a `GeoPoint` is `"51.5074,-0.1278"`, an object, a geohash string or a pair of integers. That gap is uncomfortable, because a scalar is exactly where the interesting format decisions live. `@specifiedBy` is the specification's minimal answer: rather than inventing a format language, it lets you point at a document that already describes the format. ```graphql scalar DateTime @specifiedBy(url: "https://datatracker.ietf.org/doc/html/rfc3339") ``` ## What it is, precisely It is a **built-in type-system directive** taking one required argument, `url`, of type `String!`, and its only valid location is a scalar type definition. You do not declare it; every specification-conformant server already has it. It applies to custom scalars — the built-in five do not carry one, because their coercion is written into the specification itself. ## What it does not do This is the half of the answer interviewers are actually checking, and it is entirely negative: * The server does **not** fetch the URL — not at build time, not at request time, never. * It does **not** validate anything. A value that violates the linked document is accepted if the scalar's coercion accepts it. * It does **not** change coercion. Identical schemas with and without the directive execute identically. * It does **not** make the scalar interchangeable with another server's scalar of the same name. Two schemas can both declare `DateTime` with different URLs, or one with and one without. If the URL is wrong, stale or a 404, nothing anywhere fails. It is a signpost, and signposts do not enforce. ## Who reads it Three audiences, in ascending order of usefulness. **Humans reading the schema.** A reviewer who encounters `scalar Cursor` has to go ask someone. A reviewer who encounters a scalar carrying a URL follows it. That alone justifies the directive on any schema that outlives its authors. **Schema browsers and documentation tooling.** Because the URL is surfaced in introspection — on the scalar's type entry, as its specification URL — any tool reading the schema over the wire can render it as a link without special-casing anything. This is a small but genuine exception to the general rule that applied directives are not visible through introspection. **Client generators, in principle.** A generator configured to recognise a particular specification URL can map that scalar onto a real client-side type rather than an opaque value, and can do so by URL rather than by name — which is more robust, since names are arbitrary and collide across schemas while a URL identifies a format. In practice most generators are still configured by scalar name; the URL is the more principled key, and the directive is what makes keying on it possible at all. ## Where it sits in an interview Nobody's offer turns on this. It is asked out of curiosity, or as a probe: a candidate who knows it usually also knows that a custom scalar is otherwise opaque to clients, and that is the interesting conversation underneath. The clean answer is one sentence for what it attaches, one sentence for what it does not do, and one for who reads it. ## A warning about scope Be careful not to over-claim. `@specifiedBy` documents a *scalar's value format*. It is not a general-purpose documentation mechanism — descriptions are, and every SDL construct can carry one. It does not mark deprecation, does not carry a version, and does not apply to fields, arguments, objects or enums. One argument, one location, zero runtime behaviour.