What is the top-level extensions key in a GraphQL response for, and what may a client assume about it?

## The one hole in a closed map The response envelope is deliberately closed: `data`, `errors`, `extensions`, and the specification says the top-level map must not contain any other entry. That closure is what makes the protocol safe to evolve — a future edition can define a new top-level entry knowing no conformant server has already claimed the name for something else. But servers genuinely do have things to say about a response that are neither data nor errors. `extensions` is the sanctioned answer: one named slot, explicitly reserved for implementors, into which anything else goes. Its rules are almost comically short. It is **optional** — most responses omit it. When present, its value **must be a map**, not a list and not a string. And there are **no additional restrictions on its contents**. That is the entire contract. ## Why "no restrictions" cuts both ways The freedom is the feature: a server can attach anything without breaking a conformant client, because a client that does not recognise the key simply ignores it. The freedom is also the trap: **nothing in `extensions` is specified, so nothing in it is portable.** Two servers built on different stacks will not agree on the keys inside it, and there is no schema, no introspection and no version negotiation covering it. A client that reads `extensions.someKey` and behaves differently based on what it finds has coupled itself to one particular server implementation through a channel with no contract and no deprecation process. The practical rule that falls out: `extensions` may inform, but it must never be load-bearing. If a client cannot render a correct result without reading `extensions`, the design is wrong and whatever it needs belongs in the schema, where it is typed, introspectable and versioned like everything else. ## A worked decision A four-person platform team owns a music catalogue graph consumed by three internal applications. Support tickets are hard to trace, so they want every response to carry a correlation id and the schema version it was produced against. The tempting move is a new top-level key: ```json { "data": { "release": { "title": "Nightshift Sessions" } }, "requestId": "c1f47b92", "schemaVersion": "2026.31" } ``` That body is non-conformant. Strict clients and validators are entitled to reject it, and the team has quietly claimed two names in a namespace they do not own. The conformant version puts exactly the same information one level down: ```json { "data": { "release": { "title": "Nightshift Sessions" } }, "extensions": { "requestId": "c1f47b92", "schemaVersion": "2026.31" } } ``` Now the information travels, no conformant client breaks, and — crucially — the team's own tooling is the only consumer. Their support workflow reads `extensions.requestId`; the three applications ignore the key entirely and would still work if it vanished tomorrow. That is the correct dependency shape. ## What does not belong there **Failures.** If something went wrong, it goes in `errors`. A server that reports a problem only through `extensions` has made itself invisible to every generic client, every logging middleware and every alert that watches for the `errors` entry — and there is no reason to, because `errors` is right there and standard. **Anything the caller must read.** Covered above, but it is the mistake worth naming twice in an interview. **Anything you would not show every caller.** The same response body reaches whoever asked, so treat the slot as public output rather than as an internal debugging channel that happens to ride along. ## Two adjacent slots not to confuse it with There is a **second `extensions` in the response**: each individual entry in the `errors` list may carry its own `extensions` map, describing that one error. Same name, different scope — the top-level one is about the response as a whole. There is also an `extensions` slot on the **request** side. The GraphQL over HTTP specification defines the request body's parameters, and alongside the document, operation name and variables it allows an `extensions` map, which ecosystem conventions use to carry per-request metadata to the server. Again the same name, again a different direction of travel, and again unrestricted contents. Being able to say which of the three you mean, unprompted, is most of what a senior answer to this question looks like. ## Why it is a nice-to-know Nobody is turned down for not knowing this. It is a small, well-defined corner of the envelope that most engineers never touch, because the ecosystem conventions that use it are handled inside client libraries. But an interviewer who asks it learns quickly whether the candidate reasons about protocol namespaces and vendor coupling, or reaches straight for a new top-level key.