You deployed a change and the API response looks different. Or two environments should return the same data and don’t. Or a config file changed and you want to know what. Comparing JSON sounds simple, but a plain text diff is often the wrong tool.
Why text diffs mislead
Run diff a.json b.json on two responses and you may get hundreds of changed lines even if nothing meaningful changed. The usual reasons:
- Key order.
{"a":1,"b":2}and{"b":2,"a":1}are the same JSON object. A text diff sees them as different. - Formatting. One file is minified, the other indented with tabs. Every line differs.
- Whitespace and line endings. Windows and Unix line endings alone can mark every line changed.
- Insertions shift everything. Adding one item to the start of an array makes a text diff think every later line moved.
A structural diff parses both documents and compares the data itself, so formatting and key order stop mattering.
Compare with the JSON Diff tool
- Open JSON Diff.
- Paste the original in the left pane and the changed version on the right.
- Review the result. Every difference is listed by path, such as
$.user.address.city, and marked as added, removed or changed.
Because paths are explicit, you can see at a glance that $.items[2].price went from 9.99 to 10.99, without hunting through nested braces.
If either side fails to parse, fix that first. The JSON Formatter gives the line and column, and common JSON errors explains the usual culprits.
Reading the results
| Marker | Meaning |
|---|---|
| Added | The path exists only in the new version |
| Removed | The path exists only in the old version |
| Changed | The path exists in both but with different values or types |
Type changes deserve attention. "42" becoming 42 looks harmless but can break strict clients. Changing null to [], or an object to an array, is a schema change, not a data change.
Common comparison tasks
Before and after a code change
Capture the response from the same request before and after your change, then diff them. Only the fields you meant to alter should show up. If updatedAt or requestId changes on every call, those are noise; note them and ignore them.
Staging versus production
Request the same resource from both. Differences in IDs or timestamps are expected. Differences in structure, such as a missing field, point to a version mismatch or a bad deployment.
API versions
Diff a v1 and v2 payload to build a migration checklist: what was renamed, what was removed, what is new.
Config files
Compare package.json, feature flag exports, or infrastructure settings. Because order is ignored, a reformatted or re-sorted config produces an empty diff, which is exactly right.
Postman collections
Two exports of the same collection show which requests were added or edited. For a more readable view, load each in the Postman Collection Viewer and compare the tables, or diff the raw exports here.
How arrays are compared
Objects are compared by key, so order does not matter. Arrays are trickier because order often is meaningful.
- Compared by position.
[1,2,3]versus[3,2,1]differ at every index. That is correct for ordered data such as steps or coordinates. - Inserting shifts later items. Adding an item at the start makes every following index look changed. If your array is really a set of records with IDs, sort both sides by that ID first, or compare the records individually.
If order should not matter, normalise first: sort the arrays by a stable key before comparing. Sorting object keys with the formatter’s Sort keys option also gives you a canonical form that makes any text diff tool behave better.
Diffing on the command line
If you want to script it:
# normalise key order and indent, then use the regular diff
diff <(jq -S . a.json) <(jq -S . b.json)jq -S sorts keys, which handles the ordering problem. It does not fix the array-shift issue, but it is a good quick check. For richer output, the jd and jsondiffpatch tools produce structured patches.
Tips for useful diffs
- Strip volatile fields (timestamps, request IDs, tokens) from both sides before comparing, so real differences stand out.
- Compare like with like. Use the same request parameters, the same user and the same data.
- Keep samples small. For huge responses, extract just the relevant section with JSONPath first.
- Mind secrets. Responses often include tokens or personal data. A client-side tool keeps both documents in your browser; nothing is uploaded.
- Save evidence. Copy the path list into your pull request or ticket so reviewers can see exactly what changed.
When the diff is large
A diff with hundreds of entries usually means one of three things: the data really differs (different records or environments), something systematic changed (a field renamed everywhere), or sorting is different. Look at the first few entries for a pattern. If every path ends in the same field name, a rename is the likely cause. If paths differ only in an array index, check ordering.
Related guides
For turning the result into something to share, see JSON to Excel. To find the one field you care about in a huge response, read how to view large JSON files.