Guide
How to Compare Two JSON Files
Comparing two JSON documents answers a specific question: what changed between them. A plain text diff can mislead you here, because JSON that means the same thing can be written differently. This guide explains how a structural JSON diff works and when to reach for it.
Why a text diff falls short
A line-based text diff compares characters. That works for source code, where layout carries meaning, but it misfires on JSON. Reformat a file, reorder two keys, or change the indentation, and a text diff lights up every affected line even though the data is identical.
{ "a": 1, "b": 2 }
{ "b": 2, "a": 1 }These two objects are equal as data. Their keys are in a different order, but an object is an unordered set of keys, so nothing actually changed. A text diff would still flag them as different.
What a structural diff does
A JSON diff parses both sides and compares the data, not the text. It walks the two documents together and reports three kinds of change:
- Added: a key or array item that exists on the second side but not the first.
- Removed: a key or item that exists on the first side but not the second.
- Changed: a key that exists on both sides but has a different value.
Because it compares structure, reordered object keys are treated as equal, and it can look inside nested objects and arrays to report a change at the exact level where it happens.
Arrays need a little thought
Objects are unordered, but arrays are ordered, so position matters. If you insert an item at the front of an array, every item after it shifts by one, and a positional diff may report the whole tail as changed. That is technically correct, since each index now holds a different value, but it is worth knowing so the result does not surprise you.
When you care about whether a set of items changed rather than their order, sort both arrays first, then compare. When order is part of the meaning, compare them as they are.
Compare two documents
- Put the original JSON on one side and the version you want to check on the other, by pasting or importing each.
- Scan the highlighted additions, removals, and changes.
- Drill into nested sections to see exactly which field moved.
The comparison runs in your browser, so two private API responses or config snapshots never leave your device.
When comparing JSON helps most
- Checking what an API response changed between two releases.
- Finding the one setting that differs between a local and a production config.
- Deciding whether a test fixture needs updating or whether output actually regressed.
- Reviewing a webhook payload against a known-good sample.
FAQ
Why not just use a text diff?
A text diff compares characters, so reformatting or reordering keys shows up as changes even when the data is identical. A structural JSON diff compares the data itself and ignores those cosmetic differences.
Does key order matter?
No. Objects are unordered sets of keys, so a structural diff treats two objects with the same keys and values as equal regardless of order.
Why does reordering an array show so many changes?
Arrays are ordered, so inserting an item shifts every later index. A positional diff reports each shifted index as changed. Sort both arrays first if you only care whether the set of items changed.