In a Go patch API, how do you tell an omitted JSON field from an explicit null when decoding?

## The problem A partial-update endpoint — a controller that reconciles a declared spec, a PATCH handler, a config overlay — has to distinguish three things a client can say about a field: 1. **absent** — I am not talking about this field; leave it as it is. 2. **null** — I am talking about this field; clear it. 3. **a value** — set it to this, including when "this" is `0`, `false` or `""`. Get it wrong and the failure is a wrong zero value: a spec that omits `replicas` is read as `replicas: 0`, the reconcile loop obediently scales the workload to nothing, and the only trace is a log line saying it set replicas to 0 — which is true, and useless, because the log cannot say whether the client asked for it. ## Why the obvious answers fail **A plain value type** (`Replicas int`) has one state. An absent key leaves the zero value, and the zero value is a legal input, so absent and `0` are indistinguishable. **A pointer (`*int`)** has two states, which is enough for absent-versus-value and is the right tool when `null` is not part of your contract. It cannot express three: `encoding/json` sets a settable pointer field to `nil` when it decodes `null`, which is precisely the state an absent key leaves it in. **A double pointer (`**int`)** is the reflex fix and it does not work in `encoding/json`. The field itself is a pointer, so `null` sets *it* to nil, giving the same nil the absent case gives. Anyone who proposes `**T` here has not run it. ## The mechanism that does work Two facts about the decoder combine into a solution: - `UnmarshalJSON` is called **only for keys present** in the JSON object. An absent key means the field is never visited at all. - `UnmarshalJSON` **is** called when the value is `null`, receiving the four bytes `null`, provided the field is a value of the type rather than a settable pointer to it. So a value-typed wrapper can record everything: ``` type Optional[T any] struct { Set bool Null bool Value T } func (o *Optional[T]) UnmarshalJSON(b []byte) error { o.Set = true if string(b) == "null" { o.Null = true return nil } return json.Unmarshal(b, &o.Value) } ``` `Set` false means absent. `Set` true with `Null` true means an explicit null. `Set` true with `Null` false means a value, and that value may legitimately be the zero one. Note the field must be declared as `Optional[T]`, not `*Optional[T]`: a settable pointer field would be nil'd by `null` before the method was reached. ## Two lighter alternatives **`json.RawMessage`.** It is a `[]byte` with `UnmarshalJSON` defined, so a `json.RawMessage` field is nil when the key was absent, holds the bytes `null` when the key was explicitly null, and holds the raw value otherwise. Three states, no code of your own, at the cost of a second `json.Unmarshal` when you want the value. **`map[string]json.RawMessage`.** Decode the document once into a map to learn the key set, then decode again into the typed struct. It answers the presence question for every field at once and is convenient when the handler wants to iterate over "which fields did the client mention", but it loses the typed struct's field names as the source of truth and costs a second parse of the whole document. ## Encoding is the other half A wrapper type needs a `MarshalJSON` too if the same struct is used for responses, and it has to decide what an unset field encodes as. Usually the answer is: do not reuse the patch type for responses. A response has two states, not three, and a separate struct with plain fields or pointers says that clearly. ## The part that is not code The representation is the easy half. The contract is the decision someone has to make and publish: does `null` clear a field to its zero value, remove it entirely, or restore a default? Is omitting a required field an error or a no-op? May a client send `null` for a field that has no null representation in storage? Those answers belong in the API documentation before the struct is written, because every consumer encodes an assumption about them and changing the answer later is a breaking change that no compiler will catch. ## What to say in an interview Start by ruling out `*T` with the reason — `null` nils it exactly as absence does — then give the decoder facts about `UnmarshalJSON` being called only for present keys and also for `null`, then the wrapper. Mention `json.RawMessage` as the low-effort version. Finish on the contract question, because that is the part the interviewer is actually probing for at senior level.