Matrix style explode=true serialization ambiguity in OpenAPI 3.0
0 reputation · 30 Dec 2023, 10:47 UTC
Designing an OpenAPI 3.0 document that uses matrix style parameters with explode true requires a consistent encoding decision. The specification describes style and explode semantics for serialization, but does not prescribe a canonical parsing algorithm for matrix style when explode is enabled.
Different server implementations and client SDK generators may transmit the same parameter definition as a single matrix segment or as repeated keys, and tooling often defaults to one interpretation. This leaves interoperability uncertain for consumers that expect a stable query-string shape.
For OpenAPI 3.0 and 3.1 documents intended for cross-implementation use, which serialization should be considered normative for matrix style with explode true? Does the specification define a single canonical form that servers must accept? How should the chosen interpretation be documented in the OpenAPI description to avoid divergent client behavior?