70:T452e,# v2.5.0: No more optional pointers (optionally)! ## 🎉 Notable changes ### Begone optional pointers! (optionally) One of the key things `oapi-codegen` does is to use an "optional pointer", following idiomatic Go practices, to indicate that a field/type is optional. This can be tuned on a per\-field basis, using the [`x-go-type-skip-optional-pointer` extension](#ext-x-go-type-skip-optional-pointer), but it can be a bit repetitive, or can be more complex when using an OpenAPI Overlay. As of `oapi-codegen` v2.5.0, this can be tuned in two specific ways, via the following Output Options: - `prefer-skip-optional-pointer`: a global default that you do *not* want the "optional pointer" generated. Optional fields will not have an "optional pointer", and will have an `omitempty` JSON tag - `prefer-skip-optional-pointer-with-omitzero`: when used in conjunction with `prefer-skip-optional-pointer`, any optional fields are generated with an `omitzero` JSON tag. **Requires Go 1.24\+** In both cases, there is control on a per\-field level to set `x-go-type-skip-optional-pointer: false` or `x-omitzero: false` to undo these to field(s). > [!NOTE] > The default is **not** changing. > > [We take care to avoid breaking changes](https://github.com/oapi-codegen/oapi-codegen/blob/main/CONTRIBUTING.md#when-may-we-not-change-things) so this is, as many changes, an opt\-in. See [Globally skipping the "optional pointer"](https://github.com/oapi-codegen/oapi-codegen/blob/v2.5.0/README.md#globally-skipping-the-optional-pointer) for more details. ### Generating `omitzero` JSON tags, with `x-omitzero` Related to the above functionality, it is possible to define the OpenAPI extension `x-omitzero` on fields to generate the `omitzero` JSON tag, based on the (now not\-so\-new) Go 1.24 release. Thanks to @lzap for the contribution 🚀 > [!NOTE] > `oapi-codegen` does not currently validate the Go version that the module it's generating code for. > > This could lead to the `omitzero` JSON tag being generated, but not being *actually* usable. > > Ensure that you're using a Go 1.24\+ version, and that your `go` directive (for source compatibility) is `go 1.24` or i.e. `go 1.24.1` ### Using OpenAPI 3.1 with `oapi-codegen` There's some promising behind\-the\-scenes discussions with may lead to OpenAPI 3.1 support (\#373) coming in the not\-too\-distant future 👀 In the meantime, Jamie (one of the Core Maintainers) has [written a blog post](https://www.jvt.me/posts/2025/05/04/oapi-codegen-trick-openapi-3-1/) about how to use `oapi-codegen` with OpenAPI 3.1 specs (by downgrading them to OpenAPI 3.0). ### Defining your own initialisms As a means to define your own custom initialisms, it's possible to use the `additional-initialisms` Output Option. Thanks @micaelmalta for the contribution 🚀 If your organisation uses a lot of TLAs (Two Letter Acronyms or Three Letter Acronyms) or any other sorts of initialisms, it's handy to be able to configure these yourself. For instance, if you regularly use the term CSP to refer to Cloud Service Provider, you may want `CSP` to be used in variable names. This makes it possible to define i.e. ```yaml # ... output-options: name-normalizer: ToCamelCaseWithInitialisms additional-initialisms: - CSP ``` > [!NOTE] > This only works when the `name-normaliser` Output Option is set to `ToCamelCaseWithInitialisms`. An error will occur if you've not configured this correctly. ### Minimum version of Go needed for oapi\-codegen is now 1.22.5 As part of a couple of updates in \#1888 and \#1986, we're now requiring Go \>\= 1.22.5. Similar to the bump to Go 1.21 in [v2.4.0](https://github.com/oapi-codegen/oapi-codegen/releases/tag/v2.4.0) ### Notable background work Since the last `oapi-codegen` release (all the way in September 2024 🥲) the following big changes towards the project and its ecosystem have been: - [`net/http` middleware v1.1.0: Better error handling, allow not validating `Servers` (by configuration) and return an HTTP 405 Method Not Allowed where appropriate](https://github.com/oapi-codegen/nethttp-middleware) - [Jamie posted a look back at the last year](https://github.com/oapi-codegen/oapi-codegen/discussions/1985) - Notably also writing up explicitly [how the project is currently governed](https://github.com/oapi-codegen/governance) - [`runtime`: fixes for `map`s and `x-go-type-skip-optional-pointer`](https://github.com/oapi-codegen/runtime/releases/tag/v1.1.2) ## 🚀 New features and improvements * feat(client): Add `Bytes()` to `ClientWithResponses` responses (\#1780) @grongor * feat(generate): allow generating Server URL boilerplate (\#2002) @jamietanna * feat(output\-options): add `prefer-skip-optional-pointer-on-container-types` (\#1979) @jamietanna * feat(output\-options): add `prefer-skip-optional-pointer` to default to skipping optional pointers (\#1694) @aksdb * feat(output\-options): add `yaml-tags` option (\#1798) @deitch * feat(templates): consolidate logic for whether to use an optional pointer (\#1981) @jamietanna * feat(x\-deprecated\-reason): add default deprecation message (\#2022) @jamietanna * feat: allow specifying `additional-initialisms` (\#1733) @micaelmalta ## 🐛 Bug fixes * Handle leading underscores in property names (\#1822) @tobio * fix(codegen): allow exposing the input spec's `operationId` (\#1945) @jamietanna * fix(codegen): allow using x\-go\-type and x\-go\-type\-skip\-optional\-pointer together (\#1957) @Nivl * fix(output\-options): obey `prefer-skip-optional-pointer` in reference types \+ add tests for `preferskipoptionalpointer` (\#2021) @jamietanna * fix(overlay): correctly resolve references after Overlay application (\#1825) @jgraeger * fix(stdhttp): correctly generate root paths (\#1953) @jamietanna * fix: Print the warning message to stderr instead of stdout (\#1895) @ignassew * fix: create directories if they do not exist before writing output file (\#1994) @kf\-pineapple * fix: don't generate an "optional pointer" for unknown types (\#610) @jens1205 ## 📝 Documentation updates * docs: add example for how to downgrade OpenAPI 3.1 to 3.0 (\#1966) @jamietanna * Add blog post about using oapi\-codegen in a Chi project (\#1791) @0xi4o * Fix broken anchor link for validation middleware section (\#2013) @Park\-Jongseok * chore(tests): add additional test case for underscore naming (\#1980) @jamietanna * docs(client): document known issue with duplicated `Response` models (\#2025) @jamietanna * docs(extensions): correct typo to example (\#1999) @i\-sevostyanov * docs(extensions): don't use `

` blocks in `` (\#2019) @jamietanna * docs(extensions): update example code for `x-enumNames` (\#2000) @jamietanna * docs(middleware): clarify use of `nethttp-middleware` for other purposes (\#1951) @jamietanna * docs(sponsors): add Livepeer (\#1849) @jamietanna * docs(sponsors): update Speakeasy URL (\#1970) @ndimares * docs(std\-http\-server): warn when not using Go 1.22 (\#1967) @jamietanna * docs: add contributors image (\#1795) @jamietanna * docs: add example of using `go tool` for Go 1.24\+ (\#1908) @jamietanna * docs: fix GitHub flavoured markdown (\#1934) @MarvinJWendt * docs: fix typo in flags usage (\#1796) @AlekSi * docs: note the use of a multi\-module `tools.go` (\#1788) @jamietanna * docs: simplify go tool example (\#1910) @gaiaz\-iusipov - docs(additional\-initialisms): add a usage example (\#2026) @jamietanna ## 👻 Maintenance * build(labels): add additional labelling (\#1848) @jamietanna * build(labels): add autolabeller for "no `main` branch please" (\#1847) @jamietanna * build: build against Go 1.24 (\#1901) @jamietanna * build: ensure separately named "Check results" steps (\#1850) @jamietanna * chore(examples): use Go 1.24 with Go 1.24 example (\#1925) @jamietanna * chore(tests): add additional test case for underscore naming (\#1980) @jamietanna * chore: don't use non\-GitHub URL for tests (\#1926) @jamietanna * fix(output\-options): obey `prefer-skip-optional-pointer` in reference types \+ add tests for `preferskipoptionalpointer` (\#2021) @jamietanna ## 📦 Dependency updates

13 changes

* fix(deps): update module github.com/getkin/kin\-openapi to v0.132.0 (\#2024) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps): update module github.com/getkin/kin\-openapi to v0.131.0 [security] (\#1986) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): update module github.com/golangci/golangci\-lint to v2.2.2 (\#2014) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps): update module github.com/speakeasy\-api/openapi\-overlay to v0.10.2 (\#1973) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): update module github.com/golangci/golangci\-lint to v2 (\#1940) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): update actions/setup\-go digest to d35c59a (\#1969) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps)!: update module github.com/speakeasy\-api/openapi\-overlay to v0.10.1 (\#1888) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): pin dependencies (\#1948) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): update module github.com/golangci/golangci\-lint to v1.64.5 (\#1871) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps): update module golang.org/x/text to v0.20.0 (\#1792) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps): update module github.com/stretchr/testify to v1.10.0 (\#1844) @[renovate[bot]](https://github.com/apps/renovate) * chore(deps): update module github.com/golangci/golangci\-lint to v1.62.2 (\#1828) @[renovate[bot]](https://github.com/apps/renovate) * fix(deps): update module github.com/getkin/kin\-openapi to v0.128.0 (\#1794) @[renovate[bot]](https://github.com/apps/renovate)

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

## New contributors We had 16 new contributors in this release, thanks folks 🚀 * @0xi4o made their first contribution in * @AlekSi made their first contribution in * @tobio made their first contribution in * @deitch made their first contribution in * @jgraeger made their first contribution in * @grongor made their first contribution in * @micaelmalta made their first contribution in * @chailandau made their first contribution in * @MarvinJWendt made their first contribution in * @ignassew made their first contribution in * @Nivl made their first contribution in * @jens1205 made their first contribution in * @aksdb made their first contribution in * @i\-sevostyanov made their first contribution in * @Park\-Jongseok made their first contribution in * @kf\-pineapple made their first contribution in 55:["$","$L6c",null,{"entries":[{"key":["platform",{"userId":"anon"},"repo","releases",{"owner":"deepmap","repo":"oapi-codegen"},"detail","v2.5.0"],"data":{"id":"214942","version":"v2.5.0","channel":"stable","title":"v2.5.0: No more optional pointers (optionally), `omitzero`, better control over initialisms, and so much more!","publishedAt":"2025-07-15T15:52:55Z","summary":"# v2.5.0: No more optional pointers (optionally)!","notesMarkdown":"$70","attachments":[],"htmlUrl":"https://trylle.com/deepmap/oapi-codegen/releases/tag/v2.5.0","target":"main","commitSha":"13eea66b2bf673f56fc270af5699830187d01daf","publisher":{"id":-1,"login":"Ghost"},"zipballUrl":"/v1/repositories/deepmap/oapi-codegen/archive?ref=v2.5.0&format=zip","tarballUrl":"/v1/repositories/deepmap/oapi-codegen/archive?ref=v2.5.0&format=tar.gz","isDraft":false,"isPrerelease":false},"fetchedAt":1793412588311}],"children":"$L71"}]