Comparing Two JSON Files: A Guide to JSON Diffing

Why a text diff fails for JSON

The standard Unix diff command compares files line by line. For prose text and source code where line order is meaningful, this works well. For JSON, it's often useless or actively misleading.

Consider two JSON objects that represent the same data with keys in a different order:

// File A
{"name": "Alice", "role": "admin", "active": true}

// File B
{"active": true, "name": "Alice", "role": "admin"}

A text diff reports the entire line as changed, even though the data is identical. Now consider one key actually changed:

// File A (formatted)             // File B (formatted, role changed)
{                                 {
  "name": "Alice",                  "name": "Alice",
  "role": "admin",                  "role": "editor",
  "active": true                    "active": true
}                                 }

A JSON-aware diff reports exactly: role changed from "admin" to "editor". Nothing else changed. A text diff would report the same result, but only because both files happen to be formatted the same way. If one file was minified, a text diff would show every single character as different, obscuring the one real change.

What a JSON diff shows

A JSON diff compares two JSON objects recursively and reports three types of difference:

• Added keys — a key exists in the second JSON but not the first.
• Removed keys — a key exists in the first JSON but not the second.
• Changed values — a key exists in both, but its value differs.

The diff operates on the parsed structure, not the raw text. This means formatting differences (indentation, key order, trailing whitespace) are ignored completely. Only semantic differences in the data are reported.

Common use cases for JSON diff

• API change detection. Compare a staging API response to a production response to see exactly what changed between releases.
• Config file review. Before deploying a configuration change, diff the old config against the new one to verify only the intended keys changed.
• Data migration verification. After migrating data from one format to another, diff sample records to confirm the transformation is correct.
• Debugging environment differences. Two environments behave differently — diff their JSON configuration to find the discrepancy.
• Audit trail. Track exactly what changed in a JSON document between two snapshots in time.

Array comparison and key order

Object key order is irrelevant to a JSON diff. The JSON spec (RFC 8259) explicitly says object members are unordered. A JSON diff tool compares object values by key name, so {"a":1,"b":2} and {"b":2,"a":1} are identical.

Array element order is significant. JSON arrays are ordered sequences — element 0 is compared to element 0, element 1 to element 1, and so on. If you insert an element at the beginning of an array, every element shifts, and the diff will show all elements as changed. This is technically correct per the spec but can be noisy in practice.

If the order of array elements doesn't matter for your use case (for example, an array of tags or permissions), sort both arrays before comparing to get a clean diff.

How to compare JSON online

Go to json-indent.com/diff.html. Paste the first JSON (the original) into the left panel and the second JSON (the modified version) into the right panel. The diff runs automatically and highlights every added key in green, every removed key in red, and every changed value with the old and new values shown side by side. You don't need to format the JSON first — the diff tool accepts both minified and formatted input.

How to compare JSON in Python

For a simple equality check, compare parsed Python objects:

import json

a = json.loads(json_string_a)
b = json.loads(json_string_b)

if a == b:
    print("Identical")
else:
    print("Different")

For a detailed diff showing exactly what changed, the deepdiff library is the standard choice:

from deepdiff import DeepDiff
import json

a = json.loads(json_string_a)
b = json.loads(json_string_b)

diff = DeepDiff(a, b, ignore_order=True)
print(diff)
# DeepDiff outputs changed values, added items, removed items

The ignore_order=True flag treats arrays as sets for comparison purposes — useful when array order is semantically irrelevant.

How to compare JSON in JavaScript

// Simple equality (order-independent for objects)
const a = JSON.parse(jsonStringA);
const b = JSON.parse(jsonStringB);

// Deep equality using JSON.stringify (order-dependent — sort keys first)
const equal = JSON.stringify(a, Object.keys(a).sort()) ===
               JSON.stringify(b, Object.keys(b).sort());

// For a proper recursive diff, use the 'deep-diff' npm package
const { diff } = require('deep-diff');
const differences = diff(a, b);

Compare JSON in your browser — free

Paste two JSON objects and see every added, removed, and changed key highlighted instantly.

Frequently Asked Questions