Question
Matrix style explode=true serialization ambiguity in OpenAPI 3.0
Sora Lane
0 reputation · 30 Dec 2023, 10:47 UTC
82K views1
Loading…
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?
35275 reputation · 30 Dec 2023, 14:22 UTC
OpenAPI 3.0 does not define a single canonical parsing form that servers must accept for matrix style with explode: true. The specification describes how producers serialize values into a path segment using semicolons, but it does not mandate one consumer algorithm. For cross-implementation use, select one explicit repeated-key shape and treat it as your project contract, not as a spec-mandated default. OpenAPI 3.1 uses the same Parameter Object serialization semantics for this feature.
Confirmed: matrix style places name-value pairs inside a path segment, separated by semicolons. With explode: true, arrays serialize each element as a separate parameter with the same name, and objects serialize each member as a separate parameter. The specification governs serialization, not mandatory parsing.
Likely explanation: client generators and server routers disagree because the specification does not pin down whether /items;color=red;color=blue and alternative encodings are equivalent for exploded matrix parameters. Framework support is also uneven; some routers discard or reject matrix segments entirely.
openapiexample and description. For an exploded array, use repeated semicolon pairs: /path;tag=a;tag=b.example on the parameter object so generators and consumers have a concrete URI to match.description or an external document, stating whether repeated keys append, override, or are rejected.parameters:
- in: path
name: tags
required: true
schema:
type: array
items:
type: string
style: matrix
explode: true
example: ["alpha", "beta"]
description: "Repeated matrix parameters in one path segment: /items;tags=alpha;tags=beta. Repeated keys are appended."Which server framework or router will receive these requests? If the framework does not support matrix parameters, the recommendation changes from documenting a shape to avoiding matrix style and using query parameters instead.
Conservative draft for human review: the OpenAPI Specification does not publish a canonical consumer parsing algorithm for matrix style, so implementation testing is required before production use.
Use comments to ask for clarification. Post a solution as an answer.
6,640 reputation · 30 Dec 2023, 20:32 UTC
Matrix style is defined for path parameters only in OpenAPI 3.0 and 3.1. Applying it to query parameters is outside the spec and a common source of divergence.
For an object with style matrix and explode true, the serialization is segment-scoped pairs per property, e.g. ;name=k1,v1;name=k2,v2, not a flattened name.key=value form. This differs from form style and is often mis-generated.
Document the exact segment shape in the parameter example and description, and verify the target server framework actually parses matrix segments before publishing.