Go omitempty vs omitzero: Zero Values, Pointers and null in JSON

In Go's encoding/json, the omitempty tag option leaves a field out of the JSON when its value is false, 0, a nil pointer, a nil interface, or an empty string, slice, map or array. It never omits a struct, so a zero time.Time is still written as "0001-01-01T00:00:00Z". The omitzero option, added in Go 1.24, leaves a field out when it holds the zero value of its type, and uses the type's IsZero() method when there is one, so it does omit an unset time.Time. Neither can tell "zero" from "not set": when 0 or false is a real answer, use a pointer.

Since Go 1.27 the encoding/json package runs on the new encoding/json/v2 implementation, but it keeps the old behaviour, including the old meaning of omitempty. The new package is where the meaning changes, as shown below.

What Each Tag Writes, Measured

We marshaled a struct with every field left at its zero value (Go 1.27.3, encoding/json), plus one pointer to 0:

Two rows are easy to miss. A struct is never "empty" to omitempty, which is why APIs written in Go so often send 0001-01-01T00:00:00Z for a date that was never set. And an empty slice that is not nil is not the zero value of a slice, so omitzero keeps it as [], while omitempty drops it. If you want both behaviours, Go allows json:"tags,omitempty,omitzero", which omits the field when it is either empty or zero.

When a Zero Is a Real Answer, Use a Pointer

omitempty on a plain int cannot send a discount of 0, a quantity of 0 or "enabled": false: those values disappear, and a client that treats a missing field as "use the default" may do something different from what you meant. Make the field a pointer:

type Settings struct {
	Discount *int  `json:"discount,omitempty"`
	Enabled  *bool `json:"enabled,omitempty"`
}

Now nil means "not set" and is left out, while a pointer to 0 or false is written. In our run, a *int pointing to 0 with omitempty produced "ptr":0, and a nil one produced nothing.

Reading JSON: Missing, null and a Value

Decoding has its own rules, and omitempty and omitzero play no part in them.

• A missing key leaves the field as it was, usually its zero value.
• null into a pointer, slice, map or interface sets it to nil.
• null into a plain string, int, bool or struct does nothing in encoding/json. We decoded {"name": null, "age": null} into a value that already held "keep" and 5; both were unchanged and no error was returned.

So with a *string field, a missing key and null both give nil. For most responses that is fine. For a PATCH request, where "nickname": null means "clear it" and a missing key means "leave it", you need a type that records whether the key was present. UnmarshalJSON is called for null but not for a missing key, so a small wrapper is enough:

type OptString struct {
	Set, Null bool
	Value     string
}

func (o *OptString) UnmarshalJSON(b []byte) error {
	o.Set = true
	if string(b) == "null" {
		o.Null = true
		return nil
	}
	return json.Unmarshal(b, &o.Value)
}

Decoding {}, {"nickname": null} and {"nickname": "Ada"} into a field of this type gave Set:false, then Set:true Null:true, then Set:true Value:Ada: three states, told apart.

Numbers: Where Generated Structs Usually Break

JSON has one number type, and Go has many. Three measured cases:

• 10.0 into an int is an error. json.Unmarshal refused both 10.0 and 10.5 for an int field ("cannot unmarshal number 10.5 into Go struct field ... of type int"). A struct generated from a sample where the price happened to be whole will fail on the first fractional price.
• Numbers in interface{} become float64. 9007199254740993 decoded into a map[string]interface{} came back as 9007199254740992, because a float64 holds integers exactly only up to 2^53. RFC 8259 warns about this range. Decode IDs into int64, which kept the exact value in our test, or call Decoder.UseNumber().
• Some APIs send numbers as strings ("id": "123"). The string tag option, json:"id,string", decodes those into an int64.

Two Defaults That Hide Mistakes

Unknown keys are ignored. A typo in a tag, or a field the server added, decodes without an error. While testing, decode with a json.Decoder and call DisallowUnknownFields(); it returned json: unknown field "extra" in our run.

Key matching ignores case. encoding/json matched the key "NAME" to a field tagged json:"name". It does not ignore underscores, though: "zip_code" did not reach a field named ZipCode that had no tag, which is why generated structs carry a tag on every field.

What Changes in encoding/json/v2 (Go 1.27)

Go 1.27 added the encoding/json/v2 and encoding/json/jsontext packages, and the old encoding/json is now implemented on top of v2 with options that keep v1 behaviour. Your existing code keeps working. If you call the v2 package directly, its defaults differ, and we saw each of these on Go 1.27.3:

The Go documentation's advice for code that should behave the same under both: keep omitempty for strings, slices, maps and arrays, where both versions agree, and use omitzero for numbers, booleans, pointers, interfaces and structs.

Choosing, in One Table

Start From a Generated Struct, Then Decide Field by Field

The FindUtils JSON to Go Struct generator writes the types and tags from a sample response, and its Omit Empty option adds ,omitempty to every field at once. From there, the decisions above are per field: which numbers should be float64 or int64, which fields need a pointer, which dates need omitzero. The JSON to Go Struct guide lists what to check in the generated output. To see which fields come and go between two responses, compare them in JSON Diff; to send a test request and look at the raw response, use the HTTP Request Builder.

Need help with a project? The team behind FindUtils takes on freelance work, such as a fast REST API or back-end service built in Go.