This release teaches the parameter binders about OpenAPI 3.1 multi-type unions, and fixes a long-standing panic on the request binding path. As with v1.6.0, new behavior is controlled by explicit settings rather than assumptions: binding stays exactly as it was unless the new options are used.

Notable Changes

Binding OpenAPI 3.1 multi-type union parameters

OpenAPI 3.1 allows a parameter's type to be a list, such as type: [string, integer]. Go has no type meaning "one of these", so generated code maps such parameters to any — which the binders previously rejected outright with can not bind to destination of type: interface, making these parameters unusable.

The binder options structs (BindStyledParameterOptions, BindQueryParameterOptions, BindStringToObjectOptions) gain a Types []string field carrying the union's member list. It is only consulted when the destination is an any; binding into every concrete Go type is completely unchanged. The value binds to the first member that parses, trying boolean, integer, number, then string — most restrictive first, since a string always parses. Member detection follows the JSON number grammar (RFC 8259), so values like 007 or +1 bind as strings rather than being silently reinterpreted as numbers.

The bound value's dynamic type is always one of bool, int64, float64, string, or (with format: byte) []byte, so a handler's type switch is stable regardless of what the spec's format says. Applications that want format: int32 / format: float to narrow the produced types to int32 / float32 can opt in via a new package-level setting, following the same pattern as DefaultQueryEncoder from v1.6.0:

func init() {
    runtime.NarrowUnionNumericFormats = true
}

Generator support for emitting Types is landing in oapi-codegen separately; the runtime side ships first so generated code can rely on it. Arrays of unions and deepObject-style parameters are not covered yet — see the Types field documentation for the exact scope.

Fix for a panic when binding numeric values into slice destinations

Since v1.2.0, binding a string that happens to parse as an integer into a non-[]byte slice destination panicked with reflect: call of reflect.Value.OverflowInt on slice Value, instead of returning an error. This was reachable from generated code on the request path: a nullable.Nullable[[]string] query parameter using the default form/explode serialization would panic on ?p=123 while returning a normal binding error on ?p=abc. These cases now return a clean can not bind to destination of type: slice error.

🚀 New features and improvements

• Bind OpenAPI 3.1 multi-type union parameters into any destinations (#154) @mromaszewicz, @claude

🐛 Bug fixes

• Fix panic binding numeric values into non-byte slice destinations (#156) @mromaszewicz, @claude

✍ Other changes

• chore: use go mod tidy instead of tidied (#148) @alexandear

📦 Dependency updates

• chore(deps): update github/codeql-action action to v4.37.7 (#152) @renovate[bot]
• chore(deps): update release-drafter/release-drafter action to v7.7.0 - autoclosed (#151) @renovate[bot]
• chore(deps): update github/codeql-action action to v4.37.5 (#150) @renovate[bot]
• fix(deps): update module github.com/labstack/echo/v5 to v5.3.1 - autoclosed (#149) @renovate[bot]
• chore(deps): update release-drafter/release-drafter action to v7.6.0 (#147) @renovate[bot]
• chore(deps): update github/codeql-action action to v4.37.2 (#146) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

• No new contributors

This is a small release which adds a global encoding setting on the runtime, to allow users to customize how to handle spaces in query arguments. This is a new minor release, since we're adding new API, even though this is a very minor feature. I imagine that in the future, we will add more settings, rather than making behavior assumptions.

🚀 New features and improvements

• Allow customizing default query encoder (#145) @mromaszewicz

📦 Dependency updates

• chore(deps): update module github.com/golangci/golangci-lint to v2.12.2 (#112) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

Sponsors

We would like to thank our sponsors for their support during this release.

This is mainly a bugfix release, but we're bumping the minor version since we also introduce a new type, Duration into our types/ package, which allows for parsing and emitting RFC3339 durations. Rather than trying to parse a duration string into a time.Duration, which requires assumptions that may not be right for everyone, we decided not to make those decisions and just store all possible fields as provided. Users can convert this to Go Duration as they see fit.

🚀 New features and improvements

• Add types.Duration for the RFC 3339 duration format (#144) @mromaszewicz

🐛 Bug fixes

• Let generated code declare whether styled parameter values are escaped (#143) @mromaszewicz
• Prefer the form struct tag over json for form encoding (#140) @mromaszewicz
• Support binding deepObject parameters into map[string]interface{} (#139) @mromaszewicz

📝 Documentation updates

• Explain how to send nested objects when style serialization fails (#141) @mromaszewicz

📦 Dependency updates

• fix(deps): update module github.com/labstack/echo/v5 to v5.3.0 (#142) @renovate[bot]
• chore(deps): update golang/govulncheck-action action to v1.1.0 (#137) @renovate[bot]
• chore(deps): update oapi-codegen/actions action to v0.8.0 (#130) @renovate[bot]
• fix(deps): update module github.com/labstack/echo/v5 to v5.2.1 - autoclosed (#126) @renovate[bot]
• chore(deps): update release-drafter/release-drafter action to v7.5.1 - autoclosed (#124) @renovate[bot]
• chore(deps): update github/codeql-action action to v4.37.0 (#123) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

This is a bug fix to address a regression introduced in oapi-codegen v2.7.0

🐛 Bug fixes

• Add missing required parameter detection (#135) @mromaszewicz

Sponsors

We would like to thank our sponsors for their support during this release.

This is a bug fix release.

Changes in v1.4.0, coupled with changes in v2.7.0 of oapi-codegen exposed some new problems. deepObject style marshaling behavior now supports encoding unicode. UTF-8 can't be directly included in parameters, so we need to % escape it.

Form binding now detects maps, which makes binding to a Nullable possible. We can't use generics around Nullable[T], so we handle maps generically, assuming they're a Nullable with its behavior assumptions.

🐛 Bug fixes

• Fix form binding of Nullables (#133) @mromaszewicz
• Percent-encode deepObject parameter wire output (#132) @mromaszewicz

📦 Dependency updates

• chore(deps): update oapi-codegen/actions action to v0.7.0 (#127) @renovate[bot]
• chore(deps): update github/codeql-action action to v4 (#107) @renovate[bot]
• fix(deps): update module github.com/kataras/iris/v12 to v12.2.11 (#11) @renovate[bot]
• chore(deps): update release-drafter/release-drafter action to v7.2.0 (#122) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

This release fixes some missing edge cases in parameter binding and styling. We now handle all the permutations of style and explode, for the first time. Lots of tests have been added to catch regressions.

🚀 New features and improvements

• Improve deepobject unmarshalling to support nullable.Nullable and encode.TextUnmarshaler (#45) @j-waters
• feat: support spaceDelimited and pipeDelimited query parameter binding (#117) @mromaszewicz

🐛 Bug fixes

• Fix form/explode=false incorrectly splitting primitive string values on commas (#119) @f-kanari

📦 Dependency updates

• fix(deps): update module github.com/labstack/echo/v4 to v4.15.1 (#105) @renovate[bot]
• fix(deps): update module github.com/labstack/echo/v5 to v5.1.0 (#120) @renovate[bot]
• chore(deps): update release-drafter/release-drafter action to v7 (#113) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

v1.3.0 introduced a regression around binding styled parameters into primitive type destinations. This regression was due to a
fix in binding matrix and label parameters. Sorry about that.

🐛 Bug fixes

• Fix regression in binding simple parameters (#115) @mromaszewicz

Sponsors

We would like to thank our sponsors for their support during this release.

🚀 New features and improvements

• feat: improve parameter handling (#109) @mromaszewicz
  Parameters now support the allowReserved property from OpenAPI 3.0.
• feat: add support for echo v5 (#89) @jinuthankachan

🐛 Bug fixes

• Fix: Query param deepObject return without assign on !required (#68) @voro015
• fix: strip style prefix for label/matrix primitive parameters (#99) (#100) @mromaszewicz
• fix: parse un-exploded query param to map (#101) @alexdulin
• fix: respect Binder interface for primitive types in BindStringToObject (#86) @vikstrous

👻 Maintenance

• chore: Update to go 1.24 (#111) @mromaszewicz

📦 Dependency updates

• chore: Update to go 1.24 (#111) @mromaszewicz

Sponsors

We would like to thank our sponsors for their support during this release.

Notable Changes

The main change in this release is the addition of new Parameter binding and styling functions, which allow the code generator to pass in the type and format from the spec. Previously, we inferred what we wanted to do based on the destination type, however, it's not always possible to decide this without information about the specification.

🚀 New features and improvements

• feat: add BindRawQueryParameter for correct comma handling (#92) @mromaszewicz
• fix: add TypeHint-aware parameter binding and styling for []byte (#97) (#98) @mromaszewicz
• Support array of objects parameters (#40) @danicc097
• Allow BindStyledParameterWithOptions to fill maps (#72) @JoZie

🐛 Bug fixes

• fix: bind Date and Time query params as scalar values (#21) (#93) @mromaszewicz
• fix: support non-indexed deepObject array unmarshaling (#22) (#96) @mromaszewicz
• fix: correct time.Time date-only fallback parsing in deepObject (#95) @mromaszewicz
• Refactor date parsing error handling (#88) @jsnfwlr
• fix: improve email validation using net/mail package (#60) @sniperwolf
• Fix deepObject marshalling losing json number format/precision (#29) @mgabeler-lee-6rs
• Fix issue 55 (#56) @mikhalytch
• fix(deepobject): support nested objects in deepObject arrays (#84) @adrianbrad

👻 Maintenance

• feat(fix): bump gin version (#51) @Gamawn
• Update golang.org/x/crypto to v0.32.0 (#59) @kojustin
• Updated Golang reference to address security vulnerability (#57) @ivan-manzhulin
• Fix linter errors (#85) @mromaszewicz
• build: capture govulncheck results as Code Scanning alerts (#80) @jamietanna

📦 Dependency updates

• chore(deps): update release-drafter/release-drafter action to v6 (#31) @renovate[bot]

Sponsors

We would like to thank our sponsors for their support during this release.

🐛 Bug fixes

• Fix #70: Use %w formatting directives when fmt.Error'ing an error. (#71) @constantoine
• Fix BindQueryParameter for optional parameters (#48) @TelpeNight
• fix: make BindQueryParameter play along with x-go-type-skip-optional-pointer (#47) @swistakm
• fix: correctly handle maps with different value types when binding (#38) @andnow873

👻 Maintenance

• docs(sponsors): add FUNDING.yml (#46) @jamietanna
• Simplify CI build matrix + build against Go 1.22 (#33) @jamietanna

📦 Dependency updates

• chore(deps): pin dependencies (#63) @renovate

Sponsors

We would like to thank our sponsors for their support during this release.