In a GraphQL multipart request, what do the operations and map fields do?

## The problem the three fields solve An operation is structured text and a file is bytes, and one request has to carry both. `multipart/form-data` lets a single body hold several named fields, some textual and some binary; the GraphQL-specific part of the convention is not that encoding but the **three roles** it assigns to fields, and the rule that binds them together. This is a community specification. It is not in the GraphQL specification and not in the GraphQL over HTTP working draft, so "where is this defined" is a fair interview question and "the spec" is the wrong answer. ## `operations` A JSON-encoded operations object: the same `query`, `variables` and `operationName` an ordinary JSON request would carry. The one difference is that every variable position a file will occupy holds `null`. That `null` is a **placeholder, not a value**. Substitution happens before the server coerces variables against their declared types, so a variable declared `[Upload!]!` never sees it. Candidates often expect a nullability error here and are surprised there is none. A JSON array in this field means several operations in one request; the paths in `map` then begin with the operation's index. That batching shape is a subject of its own — what matters here is only that the path syntax has to accommodate it. ## `map` A JSON-encoded object whose **keys** are the names of the file fields that follow — `"0"`, `"1"`, `"2"` by convention — and whose **values** are arrays of dot-separated paths into the operations object: `"variables.photo"`, `"variables.photos.0"`, and for a batched request `"1.variables.photo"`. Numeric segments index arrays. Two details are worth knowing precisely. First, the value is an **array of paths**, not one path, so a single uploaded file can be substituted at several positions — one colour-reference target used by two variables, or the same file needed by two batched operations — while crossing the wire once. Second, the map is the **only** binding between a file field and the operation. The field names carry no meaning of their own; the server does not infer anything from a filename or a field name, and a path in the map that does not exist in the operations object is a request error, rejected before execution, so the resulting `errors` entry has no path into `data` and nothing points at the mutation. ## The file fields One per file, named by the map keys, each carrying the bytes plus a client-declared filename and content type. Both of those are **claims made by the caller**. A resolver that trusts the declared content type is trusting the uploader; the check has to be against the bytes. ## The ordering is normative The convention requires `operations` first, `map` second, and the file fields after. This is not tidiness. Read in that order, the server holds the complete routing table before the first byte of the first file arrives, so it can pipe each file straight to where it belongs — a temporary file, an object store, a scanner — without buffering the entire request in memory. Field order is what makes the request **processable as a stream**. **A failure worth carrying with you.** In a museum collection graph, a digitisation bench uploaded condition photos through a hand-built request that appended the two JSON fields *after* the file fields. It passed every local test, because the development server buffered the whole body and then read the fields as a dictionary, where order is invisible. It failed in the shared environment against a server that read the body as a stream: the first file part arrived with no map, and the request was rejected outright, before any resolver ran, with an error that pointed at nothing. The assumption that broke was that form fields are a set. On this convention they are a sequence — and a server that tolerates a different order is being lenient, not compliant. ## The `Upload` scalar The convention describes the request, not the schema. The `Upload` scalar that servers pair with it is a separate convention: input-only, because there is no sensible way to serialize a file into a JSON response, and with no literal form, because a file cannot be written into a document. Whatever the resolver receives — a stream, a temporary file, a buffer — is defined by the server, not by any specification, so the SDL ports between servers and the resolver body does not. ## What stops working around it The body is no longer JSON, and that is the operational cost. Anything that assumed JSON needs explicit support for this one path: an intermediary that inspects or rewrites bodies, a document-hash handshake, a JSON-only composition layer in front of subgraphs. The upload becomes a special case at every hop it crosses, which is a large part of why teams eventually move large files out of the graph entirely.