How to compare JSON files and see what changed

{
  "name": "orders-api",
  "version": "1.4.0",
  "replicas": 2,
  "features": ["search", "export"],
  "limits": { "rps": 100, "burst": 20 }
}

{
  "name": "orders-api",
  "version": "1.5.0",
  "replicas": 3,
  "features": ["search", "export", "webhooks"],
  "limits": { "rps": 100 },
  "owner": "payments"
}

+2 −1 ~2

changed  $.version
changed  $.replicas
added    $.features[2]
removed  $.limits.burst
added    $.owner

A line-by-line diff is the wrong tool for JSON. Reorder two keys, or reformat a file from four-space indentation to two, and a text diff lights up every line while the data has not changed at all. What you usually want to know is which values are different. Compare, one of the editor’s four modes, puts a document in each pane and answers that question by structure, so the result is a short list of real changes rather than a wall of red and green.

The example above is a service configuration as it shipped in version 1.4 and the one proposed for 1.5. Before reading on, try to list the differences yourself. Some are easy to see; the missing burst limit is the kind that slips through a review.

Reading the answer

The gutter reads 5, and hovering over it gives 5 differences between the two panes. The status bar splits the same total by kind, which is the first line of the result above: two values only on the right, one only on the left and two that changed, exactly as its tooltip spells out.

Under it, the block lists the five in document order — the left document’s order, since a comparison is read against a baseline. That list is the Guide’s own rendering of what the engine returned; on screen you walk it instead. The version string and the replica count changed, webhooks joined the end of the feature list, the new owner field appeared, and the burst limit was removed. Each one is marked in both panes, so the old and the new value are side by side.

Walk through the changes

The arrows above and below the count are Previous difference and Next difference. Press Next once and the readout becomes 1/5, both panes scroll to the first change, and every further press moves one step down the list. On a long document this is faster than scrolling, because it skips everything that matches.

Next to them are three switches. Synchronise scrolling keeps the two panes moving together as you scroll either one. Highlight the differences turns the colouring off and on when you want to read a document without it. And Swap the two documents exchanges left and right, which reverses what counts as added and what counts as removed.

What counts as a difference

Key order and formatting do not

Objects are compared key by key, so moving version above name changes nothing, and neither does re-indenting either file. The comparison runs on the parsed structure, not on the characters.

Array order does

In an array, position carries meaning, so the items are lined up by their content first. An item inserted in the middle reads as a single addition instead of shifting every item after it into a change. Two items that swap places read as one removed and one added, because the list really is different.

Types and spelling are compared exactly

The string "1" and the number 1 are different values. Numbers are compared as they are written, so 1.0 against 1 shows as a change too: that catches a serialiser that started writing numbers differently, which a looser comparison would hide.

Very long arrays

Lining arrays up by content costs time in proportion to the length of both lists multiplied together. For two arrays with many thousands of items, the editor falls back to comparing them position by position, which is quick but reports an insertion near the top as a run of changes below it. It says when that has happened: the status bar’s tooltip adds a note that a large array was compared by position, so a long list of changes is never mistaken for a precise answer.

Finding your way around a large diff

The differences are marked in every view, not only in Code. Switch either pane to Tree and the changed rows carry the same colours, which is often easier to read for a deeply nested file because unchanged branches can stay folded. Each pane also keeps its own Find bar, so you can search the left document for a key while the right one stays where it is.

There is no need to format or sort either file before comparing. Since the comparison reads the structure, a minified file on one side and a neatly indented one on the other give exactly the same result as two files with matching layout.

Copying one side over the other

Once you have decided which version is right, the gutter’s copy buttons replace one document with the other: Copy left to right and Copy right to left. Both ask before they overwrite a document you have been working on.

Compare is also where a JSONPath extraction lands. When the Find bar pulls matches into the other pane, the editor switches to Compare so the two documents can differ, and it turns the highlighting off because an extract differs from its source almost everywhere. The JSONPath guide walks through that case.

Both files stay on your computer throughout. The comparison is computed in the browser tab, which makes it a reasonable place to diff production configs that should not be pasted into an online service.

Open the editor to compare your own files, or read Why a JSON Schema check says “not fully checked” for the other mode that holds two documents.