feat(extensions): add support for x-omitzero

One of the big improvements added in Go 1.24 is `omitzero`[0][1][2],
which makes it possible to omit the "zero value" of a given Go type when
marshaling to JSON, or if the `IsZero() bool` function on the type
returns `true`.

To make it possible for `oapi-codegen` to use this, we can wire in a new
extension, `x-omitzero` which allows per-field tuning of this behaviour.

This is something that is safe to generate alongside the `omitempty`
tags[3]:

> If both "omitempty" and "omitzero" are specified, the field will be
omitted if the value is either empty or zero (or both).

To validate this, we can add a new example for the extension, which
provides testing of the expected behaviour.

As this requires Go 1.24, we need to set up the boilerplate for a new
module that only runs Go 1.24.

Closes oapi-codegen#1899.

[0]: https://www.jvt.me/posts/2025/02/12/go-omitzero-124/
[1]: https://www.bytesizego.com/blog/go-124-omitzero
[2]: https://antonz.org/go-1-24/#omit-zero-values-in-json
[3]: https://pkg.go.dev/encoding/json

Author: lzap

README.md

@@ -2324,6 +2324,17 @@ Force the presence of the JSON tag `omitempty` on a field
 <tr>
 <td>
 
+`x-omitzero`
+
+</td>
+<td>
+Force the presence of the JSON tag `omitzero` on a field
+</td>
+</tr>
+
+<tr>
+<td>
+
 `x-go-json-ignore`
 
 </td>
@@ -2678,6 +2689,61 @@ Notice that the `ComplexField` is still generated in full, but the type will the
 
 You can see this in more detail in [the example code](examples/extensions/xomitempty/).
 
+### `x-omitzero` - force the presence of the JSON tag `omitzero` on a field
+
+> [!NOTE]
+> `omitzero` was added in Go 1.24. If you're not using Go 1.24 in your project, this won't work.
+
+In a case that you may want to add the JSON struct tag `omitzero` to types, you can use the `x-omitempty` extension.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: x-omitempty
+components:
+  schemas:
+    Client:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+        id:
+          type: number
+    ClientWithExtension:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+        id:
+          type: number
+          x-omitzero: true
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+	Id   *float32 `json:"id,omitempty"`
+	Name string   `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+	Id   *float32 `json:"id,omitempty,omitzero"`
+	Name string   `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xomitzero/).
+
 ### `x-go-json-ignore` - when (un)marshaling JSON, ignore field(s)
 
 By default, `oapi-codegen` will generate `json:"..."` struct tags for all fields in a struct, so JSON (un)marshaling works.

examples/extensions/xomitzero/Makefile

@@ -0,0 +1,36 @@
+SHELL:=/bin/bash
+
+YELLOW := \e[0;33m
+RESET := \e[0;0m
+
+GOVER := $(shell go env GOVERSION)
+GOMINOR := $(shell bash -c "cut -f2 -d. <<< $(GOVER)")
+
+define execute-if-go-124
+@{ \
+if [[ 24 -le $(GOMINOR) ]]; then \
+	$1; \
+else \
+	echo -e "$(YELLOW)Skipping task as you're running Go v1.$(GOMINOR).x which is < Go 1.24, which this module requires$(RESET)"; \
+fi \
+}
+endef
+
+lint:
+	$(call execute-if-go-124,$(GOBIN)/golangci-lint run ./...)
+
+lint-ci:
+
+	$(call execute-if-go-124,$(GOBIN)/golangci-lint run ./... --output.text.path=stdout --timeout=5m)
+
+generate:
+	$(call execute-if-go-124,go generate ./...)
+
+test:
+	$(call execute-if-go-124,go test -cover ./...)
+
+tidy:
+	$(call execute-if-go-124,go mod tidy)
+
+tidy-ci:
+	$(call execute-if-go-124,tidied -verbose)

examples/extensions/xomitzero/api.yaml

@@ -0,0 +1,53 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: x-omitempty
+components:
+  schemas:
+    Client:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+        id:
+          type: number
+    ClientWithExtension:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+        id:
+          type: number
+          x-omitzero: true
+    ContainerTypeWithRequired:
+      type: object
+      properties:
+        has_is_zero:
+          $ref: "#/components/schemas/FieldWithCustomIsZeroMethod"
+      required:
+        - has_is_zero
+    ContainerTypeWithOptional:
+      type: object
+      properties:
+        has_is_zero:
+          $ref: "#/components/schemas/FieldWithCustomIsZeroMethod"
+    FieldWithCustomIsZeroMethod:
+      type: object
+      properties:
+        id:
+          type: string
+        value:
+          type: number
+      x-omitzero: true
+    FieldWithOmitZeroOnRequiredField:
+      type: object
+      properties:
+        id:
+          type: string
+          x-omitzero: true
+      required:
+        - id

examples/extensions/xomitzero/cfg.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../../../configuration-schema.json
+package: xomitzero
+output: types.gen.go
+generate:
+  models: true
+output-options:
+  # to make sure that all types are generated, even if they're unreferenced
+  skip-prune: true

examples/extensions/xomitzero/generate.go

@@ -0,0 +1,3 @@
+package xomitzero
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml

examples/extensions/xomitzero/go.mod

@@ -0,0 +1,32 @@
+module github.com/oapi-codegen/oapi-codegen/v2/examples/extensions/xomitzero
+
+go 1.24
+
+replace github.com/oapi-codegen/oapi-codegen/v2 => ../../../
+
+require (
+	github.com/oapi-codegen/oapi-codegen/v2 v2.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.10.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
+	github.com/getkin/kin-openapi v0.128.0 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/invopop/yaml v0.3.1 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/speakeasy-api/jsonpath v0.6.0 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.10.2 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
+	golang.org/x/mod v0.17.0 // indirect
+	golang.org/x/text v0.20.0 // indirect
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)