Diffing JSON and YAML the Right Way
Comparing two API responses or two config manifests should be easy, but structured data has a habit of exaggerating. A pretty-printer with different settings, keys in a different order, or a stray change in indentation can make two essentially identical documents look wildly different in a plain text diff. A little preparation makes the comparison honest.
Format both sides first
A line diff can only compare lines, so a minified JSON blob on one side and a pretty-printed one on the other will look completely different even when the data is identical. The fix is to normalise the presentation before comparing: pretty-print both documents with the same indentation so each key and value sits on its own line. Now the diff operates on the real structure, and a changed value shows up as a single changed line instead of one giant line replacing another.
The same applies to YAML: consistent indentation and quoting on both sides keeps the diff meaningful. Since YAML is a superset of JSON, converting both to formatted JSON is one reliable way to compare them on equal footing.
Tame key ordering
In JSON objects and most YAML mappings, the order of keys carries no meaning — {"a":1,"b":2} and {"b":2,"a":1} are the same data. But a text diff does not know that; if one system serialises keys alphabetically and another preserves insertion order, the diff will show a storm of moves that mean nothing. Sorting keys consistently on both sides before comparing removes this false signal and leaves only genuine additions, removals and value changes.
Arrays are the exception: their order usually is meaningful, so do not sort them. Reordering a list of steps or a sequence of middleware genuinely changes behaviour, and you want the diff to show that.
Read the result
With both documents formatted and their keys ordered the same way, paste them into DiffScope and the comparison becomes trustworthy. Word-level highlighting is especially handy here: when a single nested value changes from true to false or one number is off by a digit, it lights up inside the line while the surrounding structure stays quiet.
For a final check, turn on ignore-whitespace to absorb any last indentation differences, and download the patch if you need to attach the change to a review or a ticket. The result is a clean, honest picture of how the two structures actually differ.
The takeaway
Before diffing JSON or YAML, pretty-print both sides and sort object keys the same way — but leave arrays alone. Then word-level highlighting makes a single flipped boolean or changed number obvious, and ignore-whitespace mops up the rest.
Open the tool and try it now
More guides
How Diff Algorithms Work
Every diff tool answers one question: what is the smallest set of edits that turns one text into another? Here's the idea behind LCS and the Myers algorithm.
Line Diff vs Word Diff: When to Use Each
The same change can be shown as whole swapped lines or as a few highlighted words. Here's why both granularities exist and when each one is clearer.
Reading a Git Diff Without the Guesswork
Those @@ headers and +/- lines look cryptic until you know the pattern. Here's how to read a unified diff line by line and never lose your place.