How to Compare JSON - Structural Diff Guide
Why Compare JSON?
Comparing JSON objects is essential for debugging API changes, reviewing configuration updates, validating data migrations, and understanding what changed between two versions of a document. A structural diff goes beyond text comparison — it understands the JSON hierarchy.
Types of Differences
When comparing two JSON documents, there are three types of changes:
| Added | A key or array element exists in the modified version but not the original. |
| Removed | A key or array element exists in the original but not the modified version. |
| Changed | The same key exists in both but the value is different. |
Structural vs Text Diff
A text diff (like diff or Git) compares lines of text. Reordering keys or changing indentation creates false differences.
A structural diff compares the actual data. It understands that {"a":1,"b":2} and {"b": 2, "a": 1} are identical. This eliminates noise from formatting differences.
Array Comparison
Arrays are compared by index — the first element in the original is compared to the first element in the modified version, and so on. If one array is longer, the extra elements are shown as added or removed. For complex array reordering, consider sorting both arrays first.
Side-by-Side View
In addition to the structured list view, you can switch to a side-by-side formatted view that shows both JSON documents as formatted text with colored line highlights:
- Red lines — Lines only in the original (removed)
- Green lines — Lines only in the modified (added)
- Yellow lines — Lines that changed between versions
This view is useful when you want to see the exact text differences in context, similar to a Git diff but with structural awareness.
Practical Use Cases
- API debugging — Compare responses from staging vs production to find discrepancies.
- Configuration review — See exactly what changed in a config file update.
- Data migration — Verify that transformed data matches expected output.
- Testing — Compare actual API responses against expected fixtures.