2026-09-29 · 8 min read
- openapi
- http
- api
OpenAPI parameter serialization decides how a typed value becomes text in a path, query string, header, or cookie. style selects the format family and explode selects whether arrays and objects are expanded into separate fields or packed into one value.
Generated clients and hand-written servers drift when the document leaves those keywords implicit or uses a style the generator only partially implements. Compare the wire value, not the example object in the documentation UI.
Pick a style the location allows
Path parameters use simple, label, or matrix styles. Query parameters commonly use form, and may use space-delimited, pipe-delimited, or deep-object forms when both sides support them. Headers and cookies have narrower rules because their delimiters collide with the parameter syntax.
- Set style and explode explicitly for arrays and objects.
- Avoid deep-object query forms unless every client supports them.
- Document empty-array and empty-object behavior.
- Keep parameter names stable across generated SDKs.
Treat encoding as part of the contract
Reserved characters in a path segment, a query value, and a header are not interchangeable. allowReserved changes query encoding and should be used only when the server truly expects raw reserved characters.
Publish one canonical fixture per parameter: the JSON value, the serialized text, and the parsed result. Review that triple when a generator is upgraded.
Constrain what generators may invent
Some generators ignore explode, rename parameters into camel case, or drop cookie parameters. Run the generator in CI and snapshot the request it produces for the canonical fixtures. A documentation-only example does not prove the SDK matches the server.
If two styles are temporarily accepted, document the sunset of the old style and test both until clients have moved. Silent acceptance of every delimiter makes the next parser change unsafe.
Prefer simple shapes on the wire
A scalar path parameter or a repeated query field is easier to cache, log, and implement than an object exploded into bracket notation. Move complex structures to a JSON request body when serialization style would otherwise become the API.
Content in a parameter, where the OpenAPI version supports it, is a different mechanism from style and explode. Do not mix the two in one parameter and expect every tool to apply both.
Test clients and servers on the same bytes
Use Flashman's YAML/JSON converter for the OpenAPI document, the JSON formatter for parameter examples, the URL parser for request targets, the case converter for naming differences, and diff for generator snapshots.
Cover scalars, empty collections, reserved characters, exploded and packed objects, optional omissions, headers, cookies, allowReserved, and at least one generated client against the production parser.