null or omit the field
Bottom line: `null` says the field exists with no value; omitting says the field does not exist. PATCH bodies, config merging and form prefill are where the difference bites.
Bottom line: send null when the consumer must tell "cleared" from "untouched" — in a PATCH body, omission leaves the field alone and an explicit null clears it — and keep one convention per field so responses and config merges stay stable.
The difference
{ "nickname": null }
Present, empty. The consumer knows the field was explicitly cleared.
{ }
Absent. The consumer cannot tell "never set" from "not supported".
In JavaScript the distinction is concrete:
'nickname' in obj // false — absent
obj.nickname === null // true — present and null
obj.nickname === undefined // true — both cases
Where it matters
PATCH bodies. {"nickname": null} clears the nickname. {} changes nothing. If the handler treats "null" and "missing" as the same, users can never clear the field — they can only set an empty string, which is a different thing.
Implement with key presence, not value:
if (Object.hasOwn(patch, 'nickname')) {
target.nickname = patch.nickname; // null allowed
}
Config merging. Omission inherits the default; null disables it explicitly. This is exactly how Helm and Kubernetes values behave.
Form prefill. A null renders as empty and so does a missing field, but submission differs: had a value, now cleared → send null; never filled → omit. Without the distinction, clearing looks identical to not touching.
Conventions
| Situation | Convention |
|---|---|
| Response bodies | Keep null; stable shape, simpler types |
| PATCH requests | null clears, omission preserves |
| PUT (full replace) | Omission means delete — the whole document is replaced |
| Config merge | Omission = default, null = disabled |
| Database | null for unknown or not applicable; '' for known-empty |
Keep response shapes stable. A list where some items carry avatar and others do not forces 'avatar' in item checks at every call site. avatar: null is easier to consume.
Three things not to do
Do not use "" for null. An empty nickname and an unset nickname are different states in most domains.
Do not use 0 or -1 as sentinels. Zero is a legitimate number, and the sentinel corrupts every average you compute.
Do not mix conventions per endpoint. Two conventions mean two code paths in every client.
FAQ
What decides between null and an omitted field?
Ask whether the consumer needs to distinguish "explicitly cleared" from "never set". In a PATCH body it must, so null clears and absence preserves; in responses, keeping null makes the shape stable and the client types simpler.
How does a PATCH endpoint tell clearing from leaving alone?
Check key presence, not the value: Object.hasOwn(patch, 'nickname') tells you the field was sent, and only then assign it, null included. If the handler treats null and missing as the same, users can never clear the field and can only fall back to an empty string.
Why should response bodies keep null?
A stable shape means clients do not need an 'avatar' in item check for every optional key. When some list items carry avatar and others omit it, that check gets duplicated at every call site and is easy to get wrong.