What is the difference between null and undefined in JSON?

Dark navy cover card with the title 'What is the difference between null and undefined in JSON?' in white and a green accent bar

The difference between null and undefined in JSON is simple: null is a real JSON value, and undefined doesn't exist in JSON at all. When JavaScript turns an object into JSON, a key holding undefined disappears, while a key holding null stays. So after one trip through JSON, you can only tell "empty" (null) apart from "missing" (no key).

Why JSON has null but no undefined

JSON has null because the spec lists it as one of three literal names, and it has no undefined because the spec allows nothing else. RFC 8259 says a JSON value must be an object, array, number or string, or one of false, null and true. It adds that the literal names must be lowercase and "No other literal names are allowed."

So this document is valid:

{"nickname": null}

And this one is not, whatever produced it:

{"nickname": undefined}

The null page on MDN describes null as "the intentional absence of any object value." By contrast, the undefined page notes that a variable never assigned a value is of type undefined. JSON keeps the first idea and has no word for the second.

What JSON.stringify does with undefined

JSON.stringify handles undefined in three different ways, depending on where the value sits. The JSON.stringify reference says undefined, functions and symbols are not valid JSON values, so they are "either omitted (when found in an object) or changed to null (when found in an array)."

JSON.stringify({ a: 1, b: undefined, c: null });
// '{"a":1,"c":null}'

JSON.stringify([1, undefined, null]);
// '[1,null,null]'

JSON.stringify(undefined);
// undefined (not a string)

The array rule exists because dropping an item would shift every index after it. MDN's own example, JSON.stringify({ x: [10, undefined, function () {}, Symbol("")] }), returns '{"x":[10,null,null,null]}'.

The top-level case trips people up most. The function returns undefined rather than a string, so code that calls .length on the result crashes. Our guide on why JSON.stringify returns undefined walks through that case and the other fields it silently drops.

What JSON.parse gives back

Parsing JSON never produces undefined as a stored value, but reading a missing key still does. The parser turns null into JavaScript null. If a key isn't in the text, the property doesn't exist on the result, and reading it gives undefined.

const a = JSON.parse('{"name": null}');
const b = JSON.parse('{}');

a.name;            // null
b.name;            // undefined
"name" in a;       // true
"name" in b;       // false

If you only need a fallback, the nullish coalescing operator treats both the same: ?? returns its right side when the left side is null or undefined. Write user.name ?? "Guest" and you don't care which one arrived. When the difference matters, check with in or Object.hasOwn.

Missing, null or a value: a decision table

An API field in JSON really has three states, not two: the key is missing, the key is null, or the key has a value. Here is how I'd assign them:

State in JSON Typical meaning Example
Key missing Not sent, not requested, or unknown A response that skips address because you didn't ask for it
"key": null Known, and known to be empty A user who removed their phone number
"key": "value" Known, with a value "phone": "office line"

My take: decide this per field and write it in the API docs. A written rule like "missing means unchanged, null means cleared" ends the argument before code review starts. Which convention you pick matters far less than everyone picking the same one.

For config files people edit by hand, write null. It tells the reader the setting exists and is empty. A missing key can't.

How null behaves in PATCH requests

In a PATCH request, null often means "delete this field," not "set it to null." RFC 7396, the JSON Merge Patch spec, says null values in a merge patch "indicate the removal of existing values in the target."

With merge patch you can't store an explicit null, because sending one removes the key. The RFC itself says the format suits documents that "do not make use of explicit null values." If your data model needs a stored null, merge patch is the wrong tool for that resource.

JavaScript clients hit this quietly. Say a form sets phone: undefined to clear it. JSON.stringify drops the key, the PATCH body arrives without phone, and the server leaves the old number in place. Set the field to null instead and the server removes it.

How Python and Go map null and missing fields

Other languages have their own empty value, and each maps JSON null to it differently. Python's json module decodes null to None and encodes None back as null. A missing key just isn't in the dict, so data.get("phone") returns None for both cases. Use "phone" in data when the difference matters.

Go needs more care. The encoding/json docs say a JSON null sets an interface, map, pointer or slice to nil. For any other Go type, unmarshaling null "has no effect on the value and produces no error." So a plain string field can't tell null from missing; use a pointer like *string if you need to.

On the way out, Go's omitempty tag drops a field whose value is empty: false, 0, a nil pointer, a nil interface value, or a zero-length array, slice, map or string. That means omitempty on an int also hides a real zero, which is rarely what you want.

Language JSON null becomes Missing key becomes
JavaScript null undefined (property absent)
Python None Key absent from the dict
Go (pointer field) nil nil (same as null)
Go (plain field) Unchanged zero value Unchanged zero value

How to keep undefined fields as null

If you want every key to appear in the output, convert undefined to null before the data leaves JavaScript. A replacer function does it in one line. MDN notes that if a replacer returns undefined, "the property is not included in the output," so return null instead:

const body = JSON.stringify(form, (key, value) =>
  value === undefined ? null : value
);

Don't do this blindly in PATCH requests. Under merge patch rules every null you add becomes a delete, so converting all undefined values can wipe fields the user never touched.

To see exactly which keys made it into a payload, paste it into a JSON viewer and expand the tree. Missing keys won't be there, and null values show up as their own entries. For other values JSON can't hold, see NaN and Infinity in JSON, and for the wider gap between the two formats, read JSON vs a JavaScript object.

FAQ

Is undefined valid in JSON?

No. JSON allows objects, arrays, numbers, strings and the three lowercase literals false, null and true. There is no undefined literal, so a bare undefined makes the document invalid.

What does JSON.stringify do with undefined?

Inside an object, the key is left out. Inside an array, the item is written as null. At the top level, JSON.stringify(undefined) returns undefined instead of a string.

How do I keep a key whose value is undefined?

Convert it to null before or during serialization, for example with a replacer function that returns null when the value is undefined. The key then appears in the output as null.

Should an API send null or leave the field out?

Pick one meaning per field and document it. A common rule is: leave the key out when the value was not requested or not known, and send null when the value is known to be empty.

What does null mean in a JSON PATCH request?

In JSON Merge Patch, a null value means remove that key from the target. That is why merge patch can't set a field to null; you need a different patch format for that.

Sources