JSON Diff vs Text Diff: Why Line Diffs Lie About Data

A text diff says forty lines changed. The data says one number did. Comparing JSON as structure instead of as lines is the difference between a review and a guess.

Where the forty lines come from

Two services serialise the same object. One writes keys alphabetically, the other in insertion order. One indents with two spaces, the other with four. One puts a trailing newline. The data is identical and a line diff reports that every line changed.

Now change one price inside that object. The line diff is still forty lines of churn, and the price is somewhere in the middle of it. The reviewer either reads all forty or skims and misses it. Neither is a review.

RFC 8259 is explicit that an object is an unordered collection of name/value pairs. The order a serialiser happens to use is an implementation detail, not information, and a tool that reports it as a change is measuring something the format says does not exist.

What a structural diff reports instead

Parse both documents. Walk the two trees together. Report every place they differ, by path: `$.price` changed from 19.99 to 24.99, `$.tags[2]` added, `$.stock.store` removed. Formatting and key order never enter into it, because once the text is parsed they are gone.

The JSON diff produces that list with counts for each kind of change, a filter so you can look at only the removals, and a copy button that turns the list into a bug report. The text compare tool is still the right choice for prose, code and anything where the lines themselves are the data; for JSON it answers the wrong question.

The type change: the bug a text diff cannot show

Here is a one-character difference that a line diff renders as a trivial change and that breaks code in production: `"price": 19.99` becoming `"price": "19.99"`. A number became a string. Arithmetic on it now concatenates. A comparison against a number is now false. A database column with a numeric type rejects it.

In a text diff, that is one line with two quote marks added, visually identical to a cosmetic edit. A structural diff reports it as its own category, with the type before and after named, because it is the most dangerous kind of change in an API and the easiest to miss. The same goes for null becoming an empty object, or a single value becoming a one-element array.

Where structural diffs are honest about their limits

Arrays. A JSON array is ordered, so position matters, and comparing position by position is correct. The cost is that removing the first of ten elements reports nine changed values and one removal, because element two is now where element one was.

Some tools try to be clever here and guess at insertions and deletions. The guess is right for a list of similar strings and wrong for a list of objects that happen to share a field, and when it is wrong it hides a real change behind a plausible story. The honest report is the positional one, with the limitation stated where the reader will see it, which is what the diff here does.

A workflow that catches regressions

Save a known-good API response as a file. After a deploy, fetch it again and diff the two. The output is a list of exactly what moved, with any type change at the top of the list. A removed field is a breaking change whether or not the changelog mentioned it.

The same two-file habit works for configuration. Export the config from the environment that works and the one that does not, diff them, and the answer is usually one path long. For a source that arrives as XML, the XML to JSON converter brings it into the same comparison, and the JSON formatter will tidy either side when a human needs to read it rather than a diff.

Questions people ask

Why does a text diff show changes when the JSON is the same?

Because the two documents were formatted differently: key order, indentation, line breaks. The JSON specification defines objects as unordered, so none of that is a difference in the data. A structural diff parses both sides and compares the trees, where formatting no longer exists.

What is a type change in a JSON diff?

A value whose kind differs between the two documents: a number that became a string, a null that became an object, a value that became an array. These break code and are nearly invisible in a text diff, where adding two quote marks looks like a cosmetic edit. A structural diff lists them separately with both types named.

How are arrays compared?

By position, because JSON arrays are ordered. Removing an element from the middle shows every later element as changed plus one removal at the end. Tools that guess at insertions can hide real changes when the guess is wrong, so the honest output is the positional one with the limitation stated.

When should I use a text diff instead?

For anything where the lines are the content: prose, source code, configuration in formats without a defined structure, or when you need to see exactly what characters changed inside a string. For JSON, YAML exports converted to JSON, or API responses, the structural view answers the question actually being asked.

Is my data uploaded to compare it?

No. Both documents are parsed and walked in the browser, with nothing sent anywhere. That is the right arrangement for API responses containing tokens or customer records, which is most of them.

Can it compare large JSON files?

Documents of a few megabytes compare comfortably, since both are parsed in memory in the browser. The change list is capped so that a pair with tens of thousands of differences does not freeze the page, and a diff that long is usually a sign the two documents are not versions of the same thing.

Read next

All articles
5 min read

XML to JSON: The Four Things That Do Not Map

XML and JSON both describe trees, which is why the conversion looks easy and why it never quite is. Attributes, repeats, mixed content and namespaces each need a decision.