Detecting Nested Object Changes in JSON

Real-world JSON documents are rarely flat. API responses, configuration files, and data exports typically contain objects nested several levels deep. A robust JSON diff algorithm must recursively descend into nested structures and track the full path to each change.

How recursive comparison works:

When the algorithm encounters two objects at the same key, instead of comparing them as a whole (which would report the entire object as "changed"), it descends into both objects and compares their children individually. This process repeats until it reaches leaf values (primitives) or detects additions/removals.

// Before
{
  "user": {
    "name": "Alice",
    "settings": {
      "theme": "dark",
      "notifications": {
        "email": true,
        "sms": false
      }
    }
  }
}

// After
{
  "user": {
    "name": "Alice",
    "settings": {
      "theme": "light",
      "notifications": {
        "email": true,
        "sms": true,
        "push": true
      }
    }
  }
}

The diff reports three changes at their precise paths:

• user.settings.theme: changed from "dark" to "light"
• user.settings.notifications.sms: changed from false to true
• user.settings.notifications.push: added with value true

Path representation:

Most diff tools use either dot notation (user.settings.theme) or JSON Pointer syntax (/user/settings/theme) from RFC 6901 to identify the location of each change. JSON Pointer is the format used in JSON Patch (RFC 6902).

Depth-limited diffing:

Some diff tools allow you to limit the recursion depth. At depth 0, the entire root objects are compared as a unit. At depth 1, only top-level keys are compared individually. This is useful for getting a quick overview of large documents before drilling into specific sections.

Performance considerations:

Deeply nested documents with many levels increase the number of recursive calls. For documents with 10+ nesting levels and thousands of keys, diff performance can degrade. Most practical JSON documents stay within 5-6 levels of nesting, where performance is not a concern.