In a server-side web framework, how does a JSON request body differ from a form-encoded one, and what tells the framework which arrived?

## Nothing in the bytes says what they mean A request body arrives as an ordered sequence of octets. The transport does not label them, and the framework does not guess: it reads the media type from the **`Content-Type`** request header field and uses that value as a key into a registry of body parsers. This is the whole mechanism, and it is why a correct body sent under the wrong media type fails, while the same bytes under the right one succeed. Sniffing — inspecting the first bytes and inferring the format — is deliberately avoided on the request path. It is ambiguous (`{` starts a JSON object and also plenty of text documents), and it hands an attacker a way to make the server disagree with a proxy about what a message is. ## The three shapes a handler usually receives **Structured text (`application/json` and friends).** One complete value per body, self-describing and typed. The parser produces a tree — objects, arrays, strings, numbers, booleans, null — that a binder can map onto a typed handler argument field by field. Nesting is native, so a nested request model needs no encoding tricks. **Form-encoded (`application/x-www-form-urlencoded`).** The body uses query-string syntax: `name=ada&tags=x&tags=y`. Its rules are narrow and worth knowing exactly: - every key and every value is a **string**; there are no numbers, booleans or nulls in the format; - there is **no nesting** — the value space is flat; - a **repeated key** is the only native way to express more than one value; - reserved characters are **percent-encoded**, and by long-standing convention a space may be written as `+`; - the format carries **no charset marker** of its own, so the octets behind the percent-escapes are decoded by convention or by a configured default. Any richer structure — bracketed names, dotted names, indexed names — is a framework convention layered on top of a flat list, and different frameworks spell it differently. That is why a body model that binds cleanly from JSON can come back half-empty from a form post: the flat pairs never matched the nested shape. **Raw (`text/plain`, `application/octet-stream`, media and document types).** No structural parsing. The handler wants the bytes, or the bytes decoded as text. Frameworks typically register a pass-through parser for these, or let the handler read the body itself. ## How they compare | | Structured text body | Form-encoded body | Raw body | |---|---|---|---| | Typical media type | `application/json` | `application/x-www-form-urlencoded` | `application/octet-stream`, `text/plain` | | Value types | strings, numbers, booleans, null | strings only | none — bytes | | Nesting | native | none (conventions bolted on) | not applicable | | Repeated names | arrays | repeated key | not applicable | | What the handler gets | a typed object tree | a flat multi-valued map | bytes or a string | | Usual origin | API clients, scripts | browser form submissions | uploads, webhooks, streams | ## Why the raw case matters more than it looks Some payloads must not be re-serialized. A webhook that carries a signature computes it over the **exact bytes** the sender transmitted. Parsing to a tree and writing it back changes key order, whitespace and number formatting, so the recomputed signature no longer matches. The correct pattern is to keep the original bytes available for verification and parse afterwards — the reason frameworks offer raw body access alongside typed binding, rather than only the convenient typed form. ## Failure modes a junior candidate should recognise 1. The client sends JSON but labels it `text/plain`. The registry lookup misses the JSON parser, and the request is refused with **415 Unsupported Media Type** before the handler runs — the body was never wrong, the label was. 2. The client sends a browser form post to an endpoint whose model is nested. The parser succeeds (flat pairs are valid), the binder fills almost nothing, and the handler sees defaults rather than an error. 3. Someone hand-builds a form body without percent-encoding. An `&` or `=` inside a value silently splits it into extra pairs; the body parses, the data is wrong. 4. A body is read once for logging and then again for binding, and the second read sees nothing, because the underlying stream had already been consumed. The through-line is that body parsing fails *quietly* far more often than it fails loudly. The media type is the contract that makes it fail loudly instead.