Null versus absent fields in JSON APIs

What it is

In a response, "middleName": null, no middleName key, and "middleName": "" can all mean "no middle name", but they can also mean "unknown", "not requested" and "empty". In a request, the same three can mean "do not change", "clear the value" and "set to empty". Standards take positions. JSON Merge Patch (RFC 7396, cited) gives null in a patch a special meaning, removal of the member from the target, which is why the RFC calls the format unsuitable for documents that use explicit null values. ProtoJSON (cited) tells serialisers not to emit null and parsers to accept null as a legal value for any field that leaves the field unset, as if absent. Google's JSON Style Guide (cited) advises dropping properties whose value is empty or null unless there is a strong semantic reason for their presence.

Why it matters

Clients written in languages with optional types (Go pointers, Rust Option, TypeScript undefined versus null) map these cases differently. An update endpoint that cannot tell "omitted" from "null" either clears fields by accident or cannot clear them at all.

How to apply

• Decide per API whether responses emit null for unset optional fields or omit them, document it, and do not mix. Omission keeps payloads small and matches ProtoJSON; explicit null keeps the field list stable for tabular consumers.
• For partial updates, use merge-patch semantics: absent means unchanged, null means clear, a value means set. Alternatively accept a field mask (updateMask=name,email) listing the fields the request intends to set, which also allows clearing without null.
• Never use null for "not requested" in field-selected responses; omit the field.
• Return empty collections as [], not null or absent, so clients iterate without checks.
• In the schema, express optionality (required) separately from nullability (type: ["string", "null"]); a field can be required yet nullable, or optional yet never null.
• State the default the server applies when a field is absent on create.

Pitfalls

Deserialisers that turn a missing key into a default value (0, false, empty string) before the application sees it, so "unset" is lost. PATCH bodies produced by serialising a whole client-side object, which resend every field and overwrite concurrent changes. SDKs that cannot represent "explicitly null" and therefore cannot clear a field.