How to Diff Two JSON Files

Paste both JSON documents into the two panes of the JSON Diff tool, compare them, and read the change list it produces — additions, removals and value changes, with key order and whitespace ignored. Everything runs in your browser; export the result as an RFC 6902 patch when you need a machine-readable record of the differences.

端末内で処理

ツールだけ使いたい方はJSON差分比較へキー順を無視して意味ベースで比較し、RFC 6902パッチを出力ツールを開く

以下の解説は英語のみでご覧いただけます。

Two JSON documents rarely disagree loudly. One has a key the other lacks, one nests its config a level deeper, one quotes a number the other leaves bare — and a line-by-line diff answers every one of those cosmetic differences with a wall of red. What you actually want to know is smaller and more useful: which values changed, which keys appeared or disappeared, and whether the structure you depend on is still the shape you expect.

This page walks the job end to end with the site's JSON Diff tool — four steps, each with a check you can perform before moving to the next. The whole comparison runs in your browser: the documents are parsed into syntax trees locally and never leave the tab, which is why the same procedure is safe for configs that contain hostnames, credentials you have already rotated, or customer data you would rather not paste into a stranger's form field.

Before starting, know what the tool will and will not tell you. It compares the two documents you give it — it does not know about git history, deployments, or intent. The change list is a fact about two documents, not an explanation of who changed what and why; the steps below include where to look when you need that second half of the story.

Every step below happens in the JSON Diff tool — two panes, one compare action, and a change list that ignores everything cosmetic.

If the vocabulary of objects, arrays and keys is new, the guide to what JSON is covers it in plain language before you diff anything.

The steps

Open the tool and load the first document
Open JSON Diff and put the first document in the left pane. You can paste it, drag the file onto the pane, or load the built-in example if you would rather rehearse on sample data first. Files are read by the browser itself — there is no upload step in this procedure at any point.
Check: The left pane accepts the document without a parse error, which means the JSON was valid enough to compare. A parse error there is the tool telling you which line to fix before anything else will work.
Load the second document on the right
Put the second document in the right pane the same way. The order matters for naming, not for correctness: left is the reference and right is the version being compared against it, and the Swap button trades their places if you picked the direction wrong. Once both sides are loaded, the comparison can run.
Check: Both panes hold a document rather than an error. If only one parses, the comparison cannot start — fix the failing side first rather than comparing a document against nothing.
Compare and read the change list
Run the comparison. The result is a list of real differences: keys added on one side, keys removed from the other, and values that changed underneath an unchanged key path. Key order and whitespace are deliberately ignored — {"a":1,"b":2} and {"b":2,"a":1} are the same document here, and saying so is the point of a semantic diff. Use Alt+↑ and Alt+↓ to walk the list without reaching for the mouse.
Check: A change you know exists (rename a value on purpose before comparing, if you want a rehearsal) appears as exactly one row, not as a rewrite of every line around it. That is the signal you are reading semantics, not text.
Export the differences as a patch
When the list is right, export it as an RFC 6902 JSON Patch — a small, ordered document that says add, remove and replace for each change. The patch is what turns a reading session into a record: hand it to a colleague, attach it to a ticket, or apply it to the left document elsewhere and reproduce the right side exactly.
Check: The exported patch is itself valid JSON and noticeably smaller than either document. Applying it to a copy of the left document should produce the right.

What a semantic diff deliberately ignores

The tool parses both documents into trees and compares the trees, so three kinds of difference never reach the change list. Key order: an object is a mapping, not a sequence, and no consumer reads meaning into the order its keys were written. Insignificant whitespace: indentation and spacing are presentation, and reformatting one side should not produce a single change. Number spelling where the value is equal: 1 and 1.0 name the same number in the comparisons that matter.

What does reach the list is anything that changes what the document means: a value that changed, a key that appeared or vanished, a type shift — a string "42" becoming the number 42 is a real change, and the tool classifies it as one rather than quietly accepting it. If a change you expected is missing, the honest first question is whether it was one of the cosmetic three.

Arrays: matching by position or by key

Arrays are the one place a semantic diff has to make a choice, because ["a","b"] against ["b","a"] can be read two ways: everything moved, or nothing changed and the order is meaningful. The tool lets you decide — matching by index treats the array as a sequence, while matching by a primary key field lines elements up by identity the way a database would.

For lists of records (users, hosts, events), key matching is almost always what you want: inserting a new record at the top then produces one addition instead of a churn of every row. For lists where order is the meaning — steps in a procedure, ranked results — index matching is the honest choice. Pick it deliberately rather than letting the default make the decision for you.

Big files and where the work actually runs

The comparison runs in a Web Worker, off the page's main thread, with a 100 MB ceiling per document. The practical consequence is that a large pair still takes real seconds to compare — but the tab stays alive while it works, and you can keep scrolling the change list already on screen instead of watching a frozen page.

The three-way merge mode — where a base document joins two edited branches — calculates in the page itself and stops at 8 MB for that reason. If your merge inputs are bigger than that, the two-document comparison above is still available at full size.

When a JSON diff is the wrong instrument

Two documents in different formats — a JSON config and a YAML translation of it — need one converted first, or the diff will spend all its rows saying the containers differ. Convert one side to the other's format, then compare. And when the question is not structured at all — two log files, two paragraphs of prose — a plain text comparison is the right tool, and the JSON machinery adds nothing but noise.

The reverse also holds: if you find yourself reading a change list and narrating intent out loud — "this is where they moved the timeout" — the diff has done its job and a record of the change belongs somewhere structured. The RFC 6902 export exists precisely so that the reading session can end with an artefact instead of a memory.

Frequently asked questions

Do my JSON files get uploaded when I diff them here?

No. Both documents are parsed and compared inside your browser tab — the comparison engine runs in a Web Worker on your machine, and there is no upload endpoint to send them to. You can confirm it in DevTools: open the Network panel, run a comparison, and no request carries your data. The page's Content-Security-Policy also refuses outbound connections by construction.

Why does reordering keys not show up as a difference?

Because an object is a mapping, not an ordered list — {"a":1,"b":2} and {"b":2,"a":1} carry exactly the same information, and every JSON parser builds the same tree from both. A diff that reports key reordering is really reporting formatting, which is noise for the reader who wants to know what changed semantically. Whitespace is ignored for the same reason.

What is an RFC 6902 patch and why export one?

RFC 6902 defines JSON Patch: a JSON document that lists operations — add, remove, replace, move, copy, test — each pointing at a specific path. Exporting your comparison as one turns the change list into a machine-applicable record: the same patch applied to the left document reproduces the right side, which makes it a precise hand-off for a colleague, a test fixture, or a migration script.

How large can the two JSON files be?

Up to 100 MB per document. Parsing and comparison run in a Web Worker, so a large pair takes real time but does not freeze the tab — the interface stays responsive and already-rendered rows stay scrollable while the worker works. The separate three-way merge mode has its own, smaller 8 MB ceiling because that calculation runs on the page's main thread.

Can it compare arrays without treating every row as changed?

Yes — that is the array-matching setting. Index matching compares element 0 to element 0 and is right when order carries meaning. Key matching lines elements up by a field you choose (an id, a slug, a hostname) and is right for lists of records, where inserting one new row should produce one change, not a rewrite of the list. The setting exists because neither answer is correct for every array.

Does the diff tell me which change happened first, or who made it?

No — and no diff can. A comparison sees two documents, not a timeline: it knows a value changed, and it cannot know when, by whom, or why. That history lives in version control, deployment logs, or whatever process edited the file. The patch export is the bridge: attach it to the ticket or commit where the story is being told.

ToolsByUs team · How we check our tools