Null vs. Missing Fields in JSON Diff

In JSON, there is a critical distinction between a field that is present with a null value and a field that is entirely absent. While they might seem similar, they carry different semantic meaning, and JSON diff tools treat them as fundamentally different operations.

The two states:

// Field present with null value
{ "name": "Alice", "phone": null }

// Field entirely absent
{ "name": "Alice" }

These are not the same. In the first document, the phone key exists with an explicit null value, signaling "this field is known but has no value." In the second document, the phone key does not exist at all, which could mean "this field is unknown" or "this field is not applicable."

How diff tools handle this:

• Null to absent: Reported as a removal (the key was deleted).
• Absent to null: Reported as an addition (a new key with null value was added).
• Value to null: Reported as a value change (the value was modified to null).
• Null to value: Reported as a value change (null was replaced with a new value).

// Before
{
  "name": "Alice",
  "phone": null,
  "email": "alice@example.com"
}

// After
{
  "name": "Alice",
  "email": "alice@example.com",
  "address": null
}

The diff reports:

• phone: removed (was null, now absent)
• address: added with value null

Real-world implications:

• APIs with PATCH semantics: Many REST APIs use PATCH requests where sending "phone": null means "set phone to null (clear it)" while omitting the field means "do not change phone." Confusing these two interpretations leads to data loss bugs.
• Database mapping: In SQL databases, a column value of NULL is different from the column not existing. JSON documents that map to database rows must preserve this distinction.
• JSON Merge Patch (RFC 7396): This standard explicitly uses null to signal deletion. Sending { "phone": null } removes the phone field from the target document.

Best practices:

• Use a diff tool that explicitly differentiates null values from missing keys.
• Document your API's convention for null vs. absent fields in your schema.
• In JSON Schema, use "required" to enforce field presence independently of the value being null.