In OpenAPI, how do you describe an object-valued query parameter, and when is deepObject the wrong choice?

## Why an object in a query string is awkward A query string is a flat list of name/value pairs. Anything with structure has to be projected onto that list, and there is no single standard for doing it — Rails, PHP, Spring and Express all parse slightly different conventions. OpenAPI 3.x gives you three declarations, and the interview question is really about which one you pick and what each costs. ## Option 1 — form with explode: true This is the default for query parameters, so it is what you get if you write an object schema and no serialization keywords. Each property becomes its own top-level key. For a parameter named `color` with value `{"R": 100, "G": 200, "B": 150}`, the URL is `?R=100&G=200&B=150`. The parameter's own name disappears from the wire entirely. That has two consequences: you cannot tell which object a key belonged to, and two different object parameters sharing a property name collide irrecoverably. It is acceptable only when the object is really just a shorthand for a set of independent flat parameters — and in that case you may as well declare them as separate parameters, which documents better. ## Option 2 — form with explode: false The same object becomes `color=R,100,G,200,B,150`: keys and values interleaved in one comma list. It preserves the parameter name but is unreadable, brittle if any value contains a comma, and supported inconsistently by server frameworks. It exists for completeness; it is rarely the right pick. ## Option 3 — deepObject `style: deepObject` with `explode: true` produces bracketed keys: `?color[R]=100&color[G]=200&color[B]=150`, or in the more typical case `?filter[status]=open&filter[assignee]=me`. This reads well, keeps the parameter name, and matches what several popular frameworks already parse. Its limits matter: - It is defined **only for objects** — not arrays, not primitives. - Its behaviour for **nested** objects and for arrays inside the object is not portably defined, and generators and validators differ. If your filter has `filter[range][from]` or `filter[tags][0]`, you are outside what the specification pins down and you are betting on one particular tool's interpretation. - The brackets must be percent-encoded in a strictly conforming URL, and tools differ about whether they do so. So `deepObject` is right for a **flat** bag of scalar properties, and wrong the moment the object nests. ## Option 4 — a content-typed parameter A Parameter Object may use `content` **instead of** `schema` — the two are mutually exclusive, and the `content` map must contain exactly one entry. The usual choice is `application/json`. The client serializes the value as JSON and percent-encodes it, giving `?filter=%7B%22status%22%3A%22open%22%7D`. This is the only option that expresses arbitrary nesting without ambiguity, because the serialization is a real, specified format rather than a projection onto flat keys. The costs are real too: the URL is unreadable and unpleasant to construct by hand or in a browser address bar; it is long, and long query strings run into proxy and server URL length limits; caching keys become sensitive to JSON key ordering and whitespace; and some older tooling handles `content` on parameters poorly compared to `schema`. ## Choosing A practical rule: if the object is flat and small, use `deepObject` and keep the parameter name in the brackets so the URL stays legible. If the structure genuinely nests — a filter grammar, a range object, a list of criteria — use `content: application/json` and accept the opaque URL, or reconsider whether the operation should take a body instead. If you find yourself relying on `deepObject` with nested brackets, you have left the part of the spec that different tools agree on, and the symptom will be a generated client whose URL the server silently parses into a partly-empty object. ## What to verify before writing it down Whichever you pick, check what the **server framework actually parses** first. The OpenAPI document is a description; it does not change the parser. The failure mode is quiet: the request succeeds, the filter object arrives half-populated, and the endpoint returns the unfiltered collection.