Is the persistedQuery extension defined by the GraphQL specification, or is it a convention?

## The specification reserves a room and leaves it empty The GraphQL specification is precise about exactly one thing here, and it is not persisted queries. It reserves an `extensions` entry as a map for implementation-defined data — a place implementations may put whatever they like — and then declines to say what may go in it. The response envelope's `extensions` entry is reserved that way by the specification itself; an `extensions` map among the *request* parameters is carried by the GraphQL over HTTP working draft. Neither document defines an entry called `persistedQuery`, a hash algorithm, a version number, or the error a server returns when it does not recognise a hash. So the answer to "is this in the spec?" is no. The interesting half is what fills the gap. Automatic Persisted Queries is a **convention** — an agreed wire shape that a client library and a server implementation each hard-code so that they interoperate, without any standard obliging them to. The shape is small enough to state completely: ```json { "operationName": "ClinicDaySlots", "variables": { "clinicId": "clinic-4417" }, "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "fc7cd86c2ce9a1a1004bb386539671e7bd77d84114ee78113d809324ee47b77a" } } } ``` That is the entire contract on the wire. `version` is an integer that has been `1` for as long as the convention has existed. `sha256Hash` is the lowercase hexadecimal SHA-256 digest of the operation document — 64 characters, always. ## What both ends must agree on, and what nothing checks Because nothing specifies it, there is no conformance test, no negotiation step and no capability advertisement in the protocol. Every item below is an agreement two independent implementations happen to share: * **The name of the extension entry.** A server looking for `persistedQuery` will never find `persisted_query`. * **The version integer**, and what a future value would mean. * **The algorithm and its encoding** — SHA-256, hexadecimal, lowercase. * **Exactly which text was hashed.** The digest is taken over a byte string, so the client's copy of the document and the copy it later uploads must be character-identical. Adding a single trailing newline to the document above changes the digest from `fc7cd86c…` to `28ce4466…` — a completely different key. * **The signal for a hash the server has never seen.** Conventionally an entry in the response's `errors` array whose `message` is the literal string `PersistedQueryNotFound`; the client recognises that exact string and reacts to it. Servers that implement the convention but have it switched off conventionally answer with a not-supported message instead. None of this is validated by the schema. `extensions` is not part of the type system: it is not a field, it is not an argument, it takes no directive, and it never appears in introspection. A server is free to ignore any extension entry it does not understand — which is precisely what a server without persisted-query support does with this one. ## Why "ignored" is the sharp edge Silently ignoring an unknown extension is the right default for extensibility, but it interacts badly with this particular convention, because a hash-first request deliberately omits the `query` parameter — the hash is meant to *replace* the document. Send that request to a server that has never heard of the convention and two things happen in order: the extension is discarded as unknown, and the request is then found to have no document at all. The client gets back a request error complaining about a missing query, which is a true statement about the request and a completely misleading one about the cause. Recognising that failure mode — "my hash-only requests all say there is no query" means "the server does not implement the convention", not "my hash is wrong" — is the practical payoff of knowing this is unspecified. ## Unspecified is not unusual It would be easy to hear "convention" as "fringe". It is not. Most mainstream servers implement this one, and a good deal of what people casually call "GraphQL" sits in the same category: connection-and-cursor pagination and global object identification are server conventions; per-field cache hints are a server convention; static cost analysis is a convention; even the composition directives of a federated graph come from a separate specification, not the GraphQL one. The specification itself is deliberately narrow — it defines a language, a type system and an execution algorithm, and says almost nothing about transport, caching or operational concerns. Everything operational grew up around it as convention. What the distinction buys you is a habit: when a question turns on one of these, you answer "where is this defined?" before you answer "how does it work?", because the two answers have different consequences. Specified behaviour is portable and you may rely on it. Conventional behaviour is portable *in practice*, subject to dialect drift, and the authority for "will this work against that server" is that server's documentation rather than the specification. ## Traps The common wrong answers are asserting that the specification defines persisted queries; believing that `extensions` is validated against the schema like a field or an argument; and thinking the server issues the hash to the client. It does not — the client computes the digest of its own document, and the server only ever verifies it.