What are the top-level keys of a GraphQL response body, and which of them may be absent?

## One map, three keys, nothing else The GraphQL specification defines a response as a **map** — an unordered set of key/value entries — which in practice is serialized as a JSON object. It is unusually strict about what that map may hold. Exactly three entries are defined: `data`, `errors` and `extensions`. And the rule that catches candidates out is the closing one: the top-level response map **must not contain any entry other than those three**. A server that helpfully adds `meta`, `status`, `requestId` or `traceId` alongside `data` is emitting a non-conformant response, however useful the extra key is downstream. That closure is not fussiness for its own sake. It is the mechanism that lets the protocol grow. Because no conformant server puts arbitrary keys at the top level, a future edition of the specification can define a new top-level entry without colliding with something a vendor already shipped. Everything a server wants to add goes into one designated slot instead of into the open namespace. ## `data` `data` is the result of executing the operation. Its presence answers a single question: *did execution happen at all?* * If the operation was executed, `data` is present. Its value is the result map, or the JSON value `null` if execution produced no usable result. * If the operation failed **before** execution — the document did not parse, did not validate, or a variable could not be coerced — `data` is not present at all. Not `null`; simply not a key in the map. The difference between "absent" and "present with the value null" is a genuine distinction in the envelope, and it is the one clients most often flatten by accident. ## `errors` `errors` is present **if and only if** the operation raised at least one error. Both halves of that biconditional are load-bearing. If nothing went wrong, `errors` must not be present. Not present-and-empty, not present-and-null — absent. If something did go wrong, `errors` is present and its value is a **non-empty list** of error maps. There is no conformant response containing `"errors": []`. The practical consequence is the shape of the client-side check. Testing `body.errors && body.errors.length > 0` is defensive code written by someone who does not trust the contract; the contract says presence alone is the signal. A length check does no harm, but a client that concludes "nothing failed" because the list came back empty is coding against a response no conformant server produces — and is more likely to be papering over its own deserialization bug. ## The two are not mutually exclusive The single most common misconception is that a response is *either* a data response *or* an error response, the way many hand-rolled HTTP APIs are shaped. GraphQL is not. When a field fails partway through execution, the server keeps the parts of the result it did produce and reports the failure beside them. Both keys are present, and the response is completely normal: ```json { "errors": [ { "message": "Play counts are temporarily unavailable" } ], "data": { "release": { "title": "Nightshift Sessions", "trackCount": 11, "label": { "name": "Cold Harbor Records" } } } } ``` A client that throws away `data` the moment it sees an `errors` key discards a correct, usable result — and it will do that on every partial failure, not just on catastrophic ones. ## `extensions` `extensions` is optional. If it is present its value must be a map, and the specification places **no restrictions whatsoever** on what that map contains: it is reserved for implementors to extend the protocol as they see fit. It may appear on a successful response, on a failed one, or on neither. ## Key order The specification notes that serializing `errors` before `data` is helpful when reading a response by eye during debugging. That is a serialization suggestion, not a semantic rule — JSON object keys are unordered, and no client should ever parse positionally or infer anything from where a key landed in the bytes. ## What this looks like on the wire A clean success carries one key: ```json { "data": { "release": { "title": "Nightshift Sessions", "trackCount": 11 } } } ``` A request that never executed carries one key too, but a different one: ```json { "errors": [ { "message": "Cannot query field 'trackCont' on type 'Release'." } ] } ``` Note there is no `data` key in that second body at all. ## Why interviewers ask it It is a five-second question with a long tail. The candidate who answers "data and errors" and stops has usually only ever read `response.data` out of a client library and has never looked at a raw body. The candidate who says "three keys, nothing else may be added, `errors` is absent or non-empty, and both keys together is the normal partial-failure shape" has debugged a real GraphQL response and is ready for every follow-up in this area.