JSON Diff and Compare

Structural comparison, not text comparison

A text diff on two JSON documents reports every line that differs, which means it reports a great deal that does not matter. Reindenting a file, or serialising it with a library that emits keys in a different order, produces a diff covering the entire document while changing nothing at all semantically. JSON object key order carries no meaning, so a comparison that respects it is answering the wrong question.

This tool parses both sides and walks the resulting structures. Whitespace, indentation and key order are invisible to it. What it reports is limited to three things: a value present in A and absent in B, a value present in B and absent in A, and a value present in both whose content differs.

Reading the report

Marker	Meaning
+	Present in B only. Added.
-	Present in A only. Removed.
~	Present in both, value or type differs.

Every entry is identified by its path, so ~ user.address.city tells you exactly which field moved without you having to locate it. Type changes are called out explicitly, because a field switching from number to string is a common and consequential regression that a text diff shows as an ordinary line change.

Arrays: order matters, until it does not

Arrays are ordered by definition, so by default element 0 is compared with element 0. That is correct for a list where position is meaningful, such as a sequence of steps or a ranked result set.

It is misleading for a collection where order is incidental, which is extremely common in API responses: a list of tags, permissions or records that the server happens to return in whatever order the database produced. Inserting one element at the front of such a list shifts every subsequent index and produces a diff that appears to change everything.

The treat arrays as unordered option compares arrays as sets instead, reporting only elements genuinely present on one side. Use it when position carries no meaning, and leave it off when it does.

Typical uses

• API regression checking. Capture a response before and after a deploy and confirm only the intended fields moved.
• Configuration drift. Compare the same configuration document across two environments to find what differs between staging and production.
• Reviewing generated output. When a build step emits JSON, comparing successive outputs shows whether a change had the effect you expected.

If the two documents are formatted differently and you want them normalised rather than compared, the formatter has a sort keys option that makes any two logically identical documents byte-identical.

Questions

Does key order affect the result?

No. Both documents are parsed and compared structurally, so key order and whitespace are ignored entirely. Two documents that differ only in key order are reported as identical.

When should I treat arrays as unordered?

When position carries no meaning, such as a list of tags or permissions returned in arbitrary database order. Leave it off for ranked results or ordered steps, where an element moving position is a real change.

Why is a type change reported separately?

Because it is usually more serious than a value change. A field that switches from number to string, such as an id arriving as "1024" rather than 1024, breaks consumers that rely on the type, and a plain text diff makes it look like an ordinary edit.

Are both documents uploaded anywhere?

No. Both are parsed and compared in your browser. This matters for the common case of diffing two production API responses, which frequently contain data you are not permitted to paste into a hosted service.