In a GraphQL response, how does a fragment spread's position affect key order?

## What the specification actually says about order A GraphQL response is defined as a **map**, and the specification requires that map to be *ordered*: entries appear in the order the corresponding fields were requested, with fragments expanded in place. It is one of the few places where GraphQL commits to something a JSON object normally leaves open. The specification also concedes that a serialization format with no ordered-map concept may lose the ordering, and that this is not a violation - which is the first hint that consuming order is fragile even though it is specified. The mechanism is field collection. The executor walks the selections of a selection set in document order and builds a map keyed by **response key** - the alias if a selection has one, otherwise the field name. When it meets a field whose response key is already present, it appends that selection to the existing group and the group does not move. When it meets a fragment spread, it recurses into that fragment's selection set at that point and carries on collecting. Two consequences fall straight out of that: * **A spread's fields appear where the spread is**, not at the end, and not where the fragment happens to be defined. * **A repeated response key keeps the position of its first occurrence.** The later selection merges into the earlier entry instead of appending a second one. ## The document ```graphql query ClaimExport($id: ID!) { claim(id: $id) { claimNumber status ...ClaimFinancials } } fragment ClaimFinancials on Claim { reserveCents paidToDateCents claimNumber } ``` `claimNumber` is selected twice - once inline, once inside the fragment. The response has four keys, in this order: ```json {"data":{"claim":{"claimNumber":"CLM-88214","status":"OPEN","reserveCents":412500,"paidToDateCents":186000}}} ``` `claimNumber` is first because that is where it first appeared; the fragment's copy merged into that entry and contributed no second key. The two financial fields sit exactly where the spread sits. ## The ordering assumption that broke A nightly claims export serialized this response and wrote a CSV positionally - first key to the first column, second key to the second, and so on. A refactor then moved the spread to the top of the selection set so the financial block would read first: ```graphql ...ClaimFinancials claimNumber status ``` Nothing else changed: no schema edit, no change to the fragment, no validation error, no failed request. But the key order became `reserveCents`, `paidToDateCents`, `claimNumber`, `status`, and the export wrote claim numbers into the reserve column for a full night before anyone noticed. The lesson is not that the ordering rule is wrong - the executor did precisely what the specification says. It is that the order is a property of the *document*, and the document is the artefact people refactor most freely. ## Definition position is irrelevant Moving the fragment definition above the operation, or to the end of the file, changes nothing whatsoever. Fragment definitions are top-level and unordered; only the position of the spread takes part in collection. This is a common muddle - people assume a fragment "runs" where it is written, and then reason about response order from the layout of the file rather than from the selection sets. ## Merging, briefly Two selections sharing a response key collapse into a single entry, and for composite fields their sub-selections are collected together in the same first-occurrence way, so ordering inside a merged object follows the same rule one level down. Whether such a merge is *allowed* at all - it requires the same field with the same arguments - is a separate matter; the point here is only that a legal duplicate yields one key, at the earlier position, resolved once. ## What to rely on Rely on the **set** of keys and on their values. Do not consume a response object positionally. Even with the ordering requirement in force, several things sit between the executor and the calling code: a normalized cache reassembling objects from its own store, generated result types with their own declaration order, an intermediary that re-serializes the body, or a host language whose map type is unordered. And the ordering you would be leaning on changes the moment anybody moves a spread. The contrast worth naming in an interview is **list order**, which is a completely different thing: the elements of a list field come back in the order the resolver produced them, that order is meaningful data, and callers should absolutely depend on it. Object key order is an artefact of how the document was written; list element order is a value the server chose. ## Saying it in an interview Give the rule in one sentence - collected in document order, fragments expanded in place, duplicates merging at the first occurrence - then the failure it enables, then the distinction between key order, which you should not depend on, and list order, which you should. That progression shows you know the specified behaviour and also why knowing it is not permission to use it.