oapi-codegen/runtime

⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.

This package provides helper functions for marshaling and unmarshalling HTTP parameters in headers, cookies, and query arguments in various formats, as well as functions for reading and writing form encoded data representing models.

You won't need to use this package directly, since it's imported be the boilerplate from oapi-codegen, however, you do need to use the correct version needed by the code generator, since it makes assumptions about runtime behavior.

Parameter Handling

OpenAPI 3.x parameters are characterized by three orthogonal attributes: style, location, and explode. The serialized form on the wire is determined by the combination of all three.

Styles

Parameters come in the following styles (all defined by the OpenAPI 3.x spec):

• simple — comma-separated values. The default for path and header parameters.
• label — values prefixed with ., separated by . (explode) or , (no explode). Path parameters only.
• matrix — values prefixed with ;name=, repeated (explode) or comma-separated (no explode). Path parameters only.
• form — name=value pairs joined with &. The default for query and cookie parameters.
• spaceDelimited — array elements joined by literal spaces (no explode); behaves identically to form when exploded. Query parameters, arrays only.
• pipeDelimited — array elements joined by literal | (no explode); behaves identically to form when exploded. Query parameters, arrays only.
• deepObject — nested bracket notation, e.g. name[field]=value. Query parameters, objects only, must be exploded.

Locations

Each style is only valid in specific parameter locations:

Location	Allowed styles
path	simple, label, matrix
query	form, spaceDelimited, pipeDelimited, deepObject
header	simple
cookie	form

Explode

Each style can be explode: true or explode: false, which changes how multi-value parameters (arrays and objects) are packed.

Style	Type	explode: false	explode: true
simple	primitive 5	5	5
	array [3,4,5]	3,4,5	3,4,5
	object {role:"admin", firstName:"Alex"}	firstName,Alex,role,admin	firstName=Alex,role=admin
label	primitive 5	.5	.5
	array [3,4,5]	.3,4,5	.3.4.5
	object {role:"admin", firstName:"Alex"}	.firstName,Alex,role,admin	.firstName=Alex.role=admin
matrix	primitive 5	;id=5	;id=5
	array [3,4,5]	;id=3,4,5	;id=3;id=4;id=5
	object {role:"admin", firstName:"Alex"}	;id=firstName,Alex,role,admin	;firstName=Alex;role=admin
form	primitive 5	id=5	id=5
	array [3,4,5]	id=3,4,5	id=3&id=4&id=5
	object {role:"admin", firstName:"Alex"}	id=firstName,Alex,role,admin	firstName=Alex&role=admin
spaceDelimited	primitive	not supported
	array [3,4,5]	id=3 4 5	id=3&id=4&id=5
	object	not supported
pipeDelimited	primitive	not supported
	array [3,4,5]	id=3|4|5	id=3&id=4&id=5
	object	not supported
deepObject	primitive	not supported
	array [3,4,5]	id[0]=3&id[1]=4&id[2]=5 (explode required)
	object {role:"admin", firstName:"Alex"}	id[firstName]=Alex&id[role]=admin (explode required)

The above outputs are shown unescaped for readability. In real use, values destined for query parameters are passed through url.QueryEscape (or url.PathEscape for path parameters), so reserved characters and non-ASCII bytes are percent-encoded on the wire.

Parameter Limitations

The OpenAPI 3.x parameter styles are convenient but each has at least one sharp edge. The list below documents behaviors that surprise users and the cases where round-tripping is not possible in principle.

Encoding

Configuring query encoding

By default, spaces in query strings are encoded as +, following Go's net/url (the form-urlencoded convention used by browsers). This is accepted by most servers, but it is not RFC 3986 compliant — some servers (for example, OData endpoints expecting ?filter=name%20eq%20'x') reject + for a space with 400 Bad Request.

Generated clients route all query escaping through the package-level DefaultQueryEncoder, so you can control this behavior. Two encoders ship out of the box:

• NetURLQueryEncoder — the default; encodes a space as +.
• RFC3986QueryEncoder — encodes a space as %20 for strict RFC 3986 compliance.

To opt into RFC 3986 encoding, set the default once during program initialization (it is not safe to mutate concurrently with in-flight requests, the same contract as http.DefaultClient):

func init() {
    runtime.DefaultQueryEncoder = runtime.RFC3986QueryEncoder{}
}

You may also supply your own QueryEncoder implementation (a single EscapeQueryValue method). The encoder governs query parameter values, names, and map keys (including deepObject); it does not affect path escaping or application/x-www-form-urlencoded request bodies, where + for a space is the correct, media-type-defined behavior.

• Query and path values are percent-encoded. Reserved characters (&, =, #, ?, etc.) and non-ASCII bytes are escaped via url.QueryEscape / url.PathEscape. Spaces in query values are encoded as + (form-urlencoded convention), matching url.Values.Encode(), unless DefaultQueryEncoder is changed (see above).
• Header values are passed through raw. Per RFC 7230 §3.2.6, header field values may contain visible ASCII plus space/tab; bytes ≥ 0x80 are obs-text and explicitly marked obsolete in RFC 9110. There is no generally-agreed mechanism for transporting non-ASCII text in arbitrary header values (RFC 8187 covers only header parameters like Content-Disposition filename*=). If your spec puts non-ASCII or control characters into a header parameter, the wire format is RFC-noncompliant and proxies may strip or reject the request.
• Cookie values are passed through raw. Per RFC 6265 §4.1.1, cookie values may not contain CTL, whitespace, ", ,, ;, \, or any byte ≥ 0x80. Most cookie libraries URL-encode by convention, but this package does not — if your spec puts spaces or non-ASCII into a cookie parameter, the value will not be RFC 6265-conformant.
• Map keys are percent-encoded for deepObject only. For simple, label, matrix, and form styles, map keys are emitted raw. If your map keys are non-ASCII or contain URL-reserved characters, the wire representation will not be encoded.
• allowReserved (StyleParamOptions.AllowReserved) is a query-only option per the OpenAPI 3.x spec, and only applies to values, not parameter names or map keys.

deepObject

• Bracket notation is structural, not data. MarshalDeepObject percent-encodes literal [ and ] inside values and map keys as %5B / %5D on the wire. However, once a server calls url.ParseQuery, those escapes are decoded back to [ and ] — at which point a key like p[a[b]] is ambiguous between {p: {a: {b: ...}}} and {p: {"a[b]": ...}}. UnmarshalDeepObject cannot distinguish these cases and adopts the same greedy left-to-right parse used by qs (Node), Rails Rack::Utils.parse_nested_query, and similar libraries: every unescaped [ opens a new nesting level. Literal [ and ] inside map keys cannot be round-tripped. Use a different separator in user-supplied keys if this matters to you.
• OpenAPI 3.x defines deepObject only for object schemas. This package extends it to maps and arrays for convenience (arrays are numerically indexed: p[0], p[1], …), but other tooling may not accept that wire form.
• deepObject requires explode: true. Non-exploded deepObject has no well-defined wire format; an error is returned.

spaceDelimited / pipeDelimited

• Array-only. Per the OpenAPI spec, these styles only apply to arrays of primitives. Passing a primitive or object returns an error.
• Exploded form degenerates to form. When explode: true, the separator becomes & (not space or pipe), so the output is byte-identical to form exploded. The space/pipe separator only takes effect when explode: false. This is per the OpenAPI spec, but it surprises many users.
• Unexploded spaceDelimited is RFC-fragile. Literal spaces in a query string are tolerated by most parsers but are not RFC 3986- conformant; + would be the form-urlencoded canonical form for space, but spaceDelimited is defined to use literal %20-equivalent space (the value bytes themselves are then encoded normally).

Type-conversion edge cases

• null in a struct field marshals to the literal string "null" in deepObject output. There is no distinct OpenAPI representation for absent vs. JSON-null in query parameters.
• time.Time and types.Date are formatted via RFC 3339 and 2006-01-02 respectively when used as primitives in any style. If you want a different format, wrap the field in a type that implements encoding.TextMarshaler.
• types.UUID stringifies to the canonical hyphenated 36-character form; query/path location escaping is a no-op (UUIDs are in the unreserved set).
• json.Marshaler is consulted for structs, then the result is re-decoded with UseNumber() and re-styled. Numbers therefore retain their original precision, but the round-trip through JSON means struct field tags are honored (not raw Go field names).