Practical technical guides / HTTP APIs

Encode OpenAPI Query Parameters Correctly With style and explode

The same array or object can reach the wire in seven styles. The OpenAPI 3.1.1 rules, a serializer tested against every cell of the spec's table, and what Python clients really send.

By Sandeep Belgavi · Published 2026-11-13

The same array or object can reach the wire in seven styles. The OpenAPI 3.1.1 rules, a serializer tested against every cell of the spec's table, and what Python clients really send.

One value, seven spellings

A query parameter that holds a single string is easy: ?status=open. The trouble starts with arrays and objects. Should a list of statuses be sent as status=open,returned, status=open&status=returned, status=open%20returned or status=open|returned? Should a filter object be filter[author]=Geetha, author=Geetha, or something else? Servers disagree, client libraries pick their own defaults, and code generators follow whatever their template authors remembered.

OpenAPI answers the question with two fields on each parameter: style and explode. Section 4.8.12 of the OpenAPI 3.1.1 specification defines seven styles, says which locations each applies to, and gives a table of examples for one parameter named color holding a string, an array and an object. That table is the single most useful reference for this topic, and the companion code tests a serializer against every one of its cells.

This matters more now that API descriptions are read by machines that act on them. Agent frameworks generate tools from OpenAPI documents. ADK Python 2.14.0, published on 7 November 2026 with a changelog dated 4 November, lists among its behaviour changes that OpenAPI tool query parameters now follow their declared style and explode. Before such a change, a tool generated from a correct description could still send arrays in a shape the server did not parse. Whether a human or an agent calls the API, the description is only useful if the client honours it.

The styles

The specification's styles, with the locations it allows:

  • matrix (path), from RFC 6570 path-style expansion: ;color=blue,black,brown.
  • label (path), RFC 6570 label expansion: .blue,black,brown.
  • simple (path and header), RFC 6570 simple expansion: blue,black,brown. It is the default for path and header parameters.
  • form (query and cookie), RFC 6570 form expansion: color=blue,black,brown. It is the default for query and cookie parameters.
  • spaceDelimited and pipeDelimited (query), for arrays and objects only: color=blue%20black%20brown and color=blue%7Cblack%7Cbrown.
  • deepObject (query), for objects with scalar properties: color%5BR%5D=100&color%5BG%5D=200.

explode says whether each array element or object property becomes its own name-value pair. Its default is true for form and false for every other style. So the default query serialization of an array is color=blue&color=black&color=brown, and the default for an object is R=100&G=200&B=150, with no color at all.

That last case surprises people. A form object with explode true sends the properties as top-level parameters. The parameter's own name disappears, so two object parameters with a property of the same name collide, and the server cannot tell an object property from an unrelated parameter. If you want the name kept in a query string, use deepObject, which exists for that purpose; note that the specification leaves deepObject with explode false undefined, even though false is the general default.

The table as a test suite

The specification marks combinations it does not define as n/a: for example spaceDelimited with explode true, deepObject for an array, and any of the three non-RFC 6570 styles for a plain string. A serializer should refuse those rather than invent an encoding, because whatever it invents, the server's parser will not share.

The companion serializer is about seventy lines. Its test encodes the table literally, row by row, and asserts all 37 defined cells match and every n/a cell raises an error.

TABLE = {
    ("form", True):  ("color=", "color=blue", "color=blue&color=black&color=brown", "R=100&G=200&B=150"),
    ("form", False): ("color=", "color=blue", "color=blue,black,brown", "color=R,100,G,200,B,150"),
    ("deepObject", True): (None, None, None, "color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150"),
}
for (style, explode), row in TABLE.items():
    for value, expected in zip((None, "blue", ["blue", "black", "brown"], {"R": 100, "G": 200, "B": 150}), row):
        if expected is None:
            assert_raises(ValueError, serialize, "color", value, style, explode)
        else:
            assert serialize("color", value, style, explode) == expected

If you maintain a client generator, a gateway that rewrites requests, or a tool layer that turns model output into HTTP calls, copying the table into a test like this is an afternoon's work and catches a whole class of interoperability bugs.

What common clients actually send

The companion also records what two Python clients do when handed lists and dictionaries, without sending any request. With requests 2.34.2, params={"status": ["open", "returned"]} becomes status=open&status=returned, which matches form with explode true. But params={"filter": {"author": "Geetha", "year": 2026}} becomes filter=author&filter=year: the dictionary is iterated, so only its keys are sent and the values are silently lost. The standard library's urlencode with doseq=True does the same; without doseq it sends the Python representation of the list or dictionary, brackets and quotes percent-encoded.

None of these is a bug in the library. A generic HTTP client has no idea which style your API expects. The lesson is that object parameters must be serialized deliberately, by code that reads the description, before they reach the client.

Path and header parameters

The same fields govern path and header parameters, with simple as the default. A path parameter holding an array, such as /books/{ids}, becomes /books/101,102,103; with label it becomes /books/.101,102,103 (or /books/.101.102.103 with explode true), and with matrix /books/;ids=101,102,103. Headers only allow simple, so an array header is a comma-separated list, which is also how HTTP itself combines repeated header fields. That overlap is convenient until a value contains a comma: a header value with a comma inside one element is indistinguishable from two elements. Avoid arrays of free text in headers, and percent-encode or restrict the characters allowed in path values, because a slash inside a path parameter changes the route rather than the value.

Encoding details that bite

Delimiters inside values must be percent-encoded. A tag a,b in a non-exploded form array has to be sent as a%2Cb, otherwise the server splits it into two tags. Appendix E of the specification discusses why unencoded |, [ and ] appear to work with some servers despite not being compliant; do not rely on it.

Empty arrays have no defined serialization in the table. Decide whether your API treats an absent parameter and an empty list as the same thing, document it, and make clients omit the parameter.

allowReserved, content-typed parameters and cookie parameters have their own rules and warnings in the specification, and the companion does not implement them.

Failure modes

  • A generated client uses its own default instead of the declared style.
  • An exploded form object collides with another parameter of the same name.
  • A model-generated tool call passes a nested object that the HTTP layer flattens to keys only.
  • A gateway re-encodes the query string and changes %2C to ,.
  • The server's framework parses brackets but the description says form, so the two disagree silently.

Verify it

Run the companion tests to see every cell of the table pass. For your own API, write one contract test per parameter that builds the request from the description with your production client and asserts the exact query string, and one server-side test that parses that exact string back into the expected value. When tools are generated from the description for an agent, run the same contract tests through the generated tool.

Run the example yourself

The serializer with a test for every cell of the OpenAPI 3.1.1 Style Examples table, and the script that records what requests and urlencode send. Companion code on GitHub; its README lists the prerequisites, exact commands, expected output and limits.

Primary references and authorship

Sources read 2026-11-13. Original explanation and synthetic examples by Sandeep Belgavi. Views are my own and do not represent any employer, past or present.