Detecting Added Fields in JSON

When comparing two JSON documents, one of the most common differences is the presence of fields in the second document that do not exist in the first. These are called added fields (or insertions), and they represent structural growth in your data.

How addition detection works:

A JSON diff algorithm performs a recursive key-by-key comparison of two objects. For each key present in the right-hand document but absent in the left-hand document, the algorithm records an "addition" operation. The full path to the added key is tracked so you know exactly where the new data appears in the hierarchy.

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

// After
{
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "+1-555-0100",
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

In this example, the diff would report two additions: the scalar field phone and the nested object address (with its children city and state). A good diff tool distinguishes between adding a simple value and adding an entire subtree.

Key considerations:

• Nested additions: When an entirely new object or array is added, the diff may show it as a single addition at the parent level or as multiple additions for each leaf node. The choice depends on the diff algorithm and output format.
• RFC 6902 (JSON Patch): The standard JSON Patch format represents additions with the "op": "add" operation, specifying the target path and the value to insert.
• Schema evolution: Added fields are generally backward-compatible in API versioning. Consumers that ignore unknown fields will continue to work, which is why additive changes are preferred over removals or renames.

Common pitfalls:

Developers sometimes confuse a field being added with a field that was previously null or an empty string. A diff tool treats these differently: a field that changes from null to a value is a modification, not an addition. Only keys that are entirely absent in the first document and present in the second count as additions.