How does omitempty in encoding/json/v2 differ from omitempty in encoding/json?

## Two definitions of "empty" The `omitempty` struct-tag option means "leave this member out when it is empty", and the whole difference between the packages is the word *empty*. **`encoding/json` defines it over Go values.** The member is omitted when the field holds the false boolean, any zero number, the empty string, a nil pointer or interface, or a map, slice or array of length zero. It is a fixed list, evaluated against the Go value before anything is encoded. **`encoding/json/v2` defines it over the encoded JSON.** The member is omitted when encoding it would produce an empty JSON value: `null`, `""`, `{}` or `[]`. Notice what is not on that list: `false` and `0` are perfectly ordinary JSON values, not empty ones, so v2 keeps them. ## Where they agree and where they bite They agree on the cases most code uses `omitempty` for. An empty string is dropped by both. A nil pointer encodes as `null`, so both drop it. A nil or zero-length slice encodes as `[]` (or `null`), so both drop it. A nil map likewise. They disagree on scalars: ```go type Flags struct { Verbose bool `json:"verbose,omitempty"` Retries int `json:"retries,omitempty"` Name string `json:"name,omitempty"` } f := Flags{} // encoding/json: {} // encoding/json/v2: {"verbose":false,"retries":0} ``` That is the migration hazard in this leaf. Nothing errors. A payload that was three members long grows to five, and every consumer that distinguished *absent* from *false* -- a partner treating a missing `verbose` as "use my default" -- now sees an explicit `false`. It is the mirror image of the case-sensitivity change: silent, and visible only if you diff the encoded output rather than watching for errors. ## Why v2 changed it The v1 rule has two known problems. First, it conflates "zero" with "absent" for types where those are genuinely different. A count of zero, a temperature of zero and `false` are real values, and a wire format that cannot express them forces every user of the field into a pointer or a wrapper type. Second, the v1 rule cannot see through a custom marshaler. A type whose `MarshalJSON`-equivalent produces `{}` is not one of Go's empty values, so v1 emits `"x":{}` even though the encoded result is exactly what `omitempty` was asked to suppress. Defining the rule over the *output* makes it compose: whatever produced the value, if the result is empty JSON, the member goes. ## What to use instead when you wanted the old rule The `omitzero` option -- available in the original package since Go 1.24 and in v2 -- omits a member when the field holds its type's zero value. For scalars that is exactly the v1 `omitempty` behaviour: `false` and `0` are the zero values of `bool` and `int`, so they are dropped again. It is not a universal replacement, though: a non-nil but empty slice `[]int{}` is not the zero value of its type, so `omitzero` keeps it while v1's `omitempty` dropped it. A field that needs both rules can carry both options. The cleaner answer for most APIs is neither: if absent and zero mean different things to the consumer, say so in the type with a pointer or an explicit presence flag, rather than encoding the distinction in a tag option whose meaning has now changed once. ## Auditing a migration Because the change is in the *output*, the test that catches it is an encode-and-compare, not a decode. Marshal a fixture of representative structs -- zero values included -- with both packages and diff the bytes. Every difference will be a `false`, a `0`, or a value produced by a custom marshaler, and each one is a question for whoever owns the consumer.