devtools.codes

Comparing two JSON files when the key order differs

Your tool input is processed locally in your browser and is not intentionally uploaded to our servers. Advertising and analytics providers may still process normal page, device, cookie and network information.

Two JSON documents can be functionally identical and still produce a long, noisy diff if you compare them as text. JSON objects are unordered by specification: {"a":1,"b":2} and {"b":2,"a":1} describe the same data, but a line-based text diff has no concept of that and will report every line as changed if a formatter, a different library, or a different serialisation order rearranged the keys.

This matters constantly in practice. Re-serialising a configuration file with a different tool, round-tripping data through a language whose object model does not preserve insertion order, or simply having two team members save a file with different editor settings can all reorder keys without touching a single value. A text diff treats that as a wall of changes to review; a structural diff treats it as nothing, because nothing actually changed.

A structural comparison parses both documents first and then compares values by key rather than by line position. Two objects are equal if they have the same keys mapped to equal values, regardless of the order those keys appear in the source text. Arrays are handled differently, and deliberately so: array order is meaningful in JSON, so a structural diff compares array elements by index rather than trying to guess which element moved where. A similarity-matching approach can produce a shorter report, but it is frequently wrong about which element moved, and a confidently wrong diff costs more time to untangle than a verbose but accurate one.

The practical payoff is a diff that reports what actually changed: a value that moved from one number to another, a key that was added, a key that was removed. Reordering disappears from the output entirely, because it was never a real difference to begin with.

When reviewing any JSON diff tool's output, a quick sanity check is to reorder the keys in a copy of one file and diff again. A genuinely structural comparison reports zero differences; a text-based one reports the whole file as changed.

More on comparing two JSON files when the key order differs

Why does my JSON diff show changes when I didn't change anything?

The most common cause is key reordering from re-saving, re-serialising, or round-tripping the file through a different tool. JSON objects are unordered, so a key moving position is not a real change, but a plain text diff cannot tell the difference between a moved key and an edited value. A structural JSON diff ignores order and reports only genuine differences.

Does ignoring key order also ignore array order?

No, and it should not. Array order in JSON is meaningful — [1,2,3] and [3,2,1] are different data, not a reordering of the same data. A structural diff compares array elements by their position rather than trying to match similar-looking elements across positions, which gives a predictable and accurate result rather than a guessed one.

Is a structural diff always better than a text diff for JSON?

For comparing the meaning of two JSON documents, yes. A text diff is still useful when you specifically care about formatting or byte-level changes, such as verifying a file was not accidentally re-indented. For almost every other case — comparing API responses, configs or exported data — a structural diff reports what actually matters.

The tool behind this, and related guides