JSON Diff

How the JSON Diff works

A plain text diff is the wrong tool for JSON. Reformat a file, sort its keys or minify it and a line-based diff reports nearly every line as changed, even though the data is identical. Meanwhile a single changed number on a long minified line shows up as one huge replaced line with the real change buried inside it. Comparing the parsed structure fixes both problems.

How the JSON diff works

Both inputs are parsed, then walked together from the root:

• Objects are compared key by key. A key only in the original is removed, a key only in the changed version is added, and keys in both are compared recursively. Order does not matter.
• Arrays are compared as sequences. The tool finds the longest run of items the two arrays share, in order, and reports the rest as insertions, deletions or changes. Inserting one item at the start of a list therefore shows as one addition, not as every item changing.
• Values of different types, such as "5" and 5, are reported as changed even if they look alike. That catches APIs that quietly switch a number to a string.

The Added, Removed and Changed readings count each kind of difference. If there are none, the tool says the documents are identical in content.

Reading the change list

Each line starts with a symbol and a path:

• + $.tags[2]: "sale" means a value was added.
• - $.discount: 0.1 means a value was removed.
• ~ $.price: 19.99 → 17.99 means a value changed, showing old and new.

Paths use JSONPath style: $ is the root, .key follows a key and [n] an array position counted from zero. Additions use positions in the changed document, and removals use positions in the original, so you can find each one in the file it belongs to. Long values are shortened to keep the list readable.

Exporting a JSON Patch

JSON Patch, defined in RFC 6902, is a standard format for describing changes as a list of operations. Each operation has an op (add, remove or replace), a path written as a JSON Pointer from RFC 6901, and a value where needed. Pointers use slashes, so $.items[1].qty becomes /items/1/qty, with ~ and / inside keys escaped as ~0 and ~1.

Operations in a patch apply in order, and each one sees the result of the ones before it. Removing item 2 from an array shifts every later item down by one. The tool accounts for this, so array positions in the patch are correct for the state at that step rather than for the original file. Applying the patch to the original with any RFC 6902 library produces the changed document.

Patches are useful well beyond comparison. PATCH endpoints in many REST APIs accept them, they make compact audit logs, and Kubernetes accepts them through kubectl patch --type=json.

Where comparing JSON helps

Some everyday cases where a structural diff saves time:

• Checking what an API response changed between two releases or environments.
• Reviewing a config change when the file was also reformatted.
• Comparing a test fixture with actual output to see why an assertion failed.
• Spotting drift between staging and production feature flags or settings.
• Auditing what an admin tool changed in a stored record.

Things to watch for

Numbers are compared as JavaScript numbers, so 1.0 and 1 count as equal and integers beyond about nine quadrillion may lose precision. Very large arrays, where the two lengths multiplied pass four million, fall back to comparing items position by position to keep the page responsive; an insertion near the start of such an array then shows as many changes. If a key appears twice in one object, the parser keeps the last value, which is also what your application will see.

For arrays where order carries no meaning, such as a set of tags, consider sorting both documents first. Otherwise a simple reorder shows as a set of changes, because to JSON an array's order is part of its value.

Privacy

Both documents are parsed and compared in your browser. Nothing is uploaded, so the tool is safe to use with production data, customer records or configuration that contains secrets.

Related tools