What is a semantic JSON diff?
A semantic JSON diff compares the data in two JSON documents rather than their text. A plain text diff reports a change whenever a character differs, so reordering keys or reformatting a file produces pages of noise. A semantic diff parses both documents first and then compares the resulting values.
These two documents are different as text but identical as data, and this tool reports no differences between them:
{ "name": "Ada", "roles": ["admin", "dev"] }
{
"roles": ["admin", "dev"],
"name": "Ada"
}
For display, both sides are re-formatted with the same indentation and, by default, with object keys sorted alphabetically, so the same key appears on a similar line on the left and on the right. Turn off Sort keys to see each document in its original key order; the differences found are the same either way. Arrays are never reordered.
How to compare two JSON files
- Paste the first document into the left box, or use Choose file or Load URL.
- Do the same for the second document in the right box.
- Select Compare.
- Read the summary to see how many differences were found, and use Next and Previous to step through them.
- Use the checkboxes to show only the kinds of differences you care about.
- Leave Sort keys on to line up the two sides, or turn it off to keep each document’s own key order.
If either document is not valid JSON, the tool tells you the line and column of the first problem instead of comparing.
The three kinds of differences
Every difference is identified by a JSON Pointer such as /users/0/name and has one of three types.
| Type | Meaning | Left | Right |
|---|---|---|---|
| value | Same type, different content | "age": 41 |
"age": 42 |
| type | Different JSON types | "id": 7 |
"id": "7" |
| missing | Present on one side only | "email": "a@b.c" |
(no email key) |
When a type differs or a key is missing, the tool reports that one node and does not list everything inside it. Numbers are compared by numeric value, so 1.0 and 1 are equal.
Comparing large JSON files
Large API responses, database exports and configuration dumps are where a JSON diff is most useful and where many online tools stop responding. This tool is built for them:
- Parsing and comparison run in a Web Worker, so the page stays responsive and you can cancel.
- Results use virtual scrolling, so a file with millions of lines scrolls as smoothly as a small one.
- Files are read directly from disk in your browser and are never uploaded.
Is my data uploaded?
Comparing pasted text or local files happens entirely in your browser. No part of your documents is sent to jsondiff.tools or to anyone else.
Two features do involve a server:
- Load URL first asks your browser to fetch the address directly. If that site does not allow cross-origin requests, the tool retries through the jsondiff.tools proxy and tells you it did. The proxy fetches the file, returns it to you and does not store it.
- The API receives the two values you send it so it can compare them. Request bodies are not logged.
See the privacy page for details.
JSON Diff API
The same comparison is available as a free HTTP API for scripts, CI jobs and AI agents. Send the two values as left and right:
curl -X POST https://jsondiff.tools/api/json-diff \
-H 'Content-Type: application/json' \
-d '{"left": {"name": "Ada", "age": 41}, "right": {"name": "Ada", "age": "41", "admin": true}}'
The response lists each difference with its JSON Pointer path, its type and the values on each side:
{
"equal": false,
"summary": { "total": 2, "value": 0, "type": 1, "missing": 1 },
"differences": [
{ "path": "/age", "type": "type", "left": 41, "right": "41" },
{ "path": "/admin", "type": "missing", "right": true }
]
}
For a missing difference, only the side that has the value includes it. No API key is required, any origin may call it, and the request body may be up to 1 MB. The full contract is described in the OpenAPI document.
Frequently asked questions
Does the order of keys affect the comparison?
No. Objects are compared by key name, so two objects with the same keys and values are equal no matter what order the keys appear in. By default the result is also displayed with keys sorted alphabetically so both sides line up, and you can turn that off with the Sort keys option.
How are arrays compared?
Arrays are compared position by position. The first item on the left is compared with the first item on the right, and so on. If one array is longer, the extra items are reported as missing on the other side. Inserting an item in the middle of an array therefore shifts every item after it.
Is my JSON uploaded to a server?
No. When you paste text or choose a file, parsing and comparison run locally in your browser and nothing is sent anywhere. The only exceptions are loading JSON from a URL that blocks cross-origin requests, which goes through our proxy, and calls you make to the public API.
How large a file can I compare?
There is no fixed limit in the browser. Comparison runs in a background thread and only the visible lines are rendered, so files of tens of megabytes work on a typical laptop. The practical limit is your browser's memory. The API accepts request bodies up to 1 MB.
Does it support JSON with comments or trailing commas?
No. The parser follows the JSON standard (RFC 8259) strictly, so comments, trailing commas, single quotes and unquoted keys are reported as errors with the line and column where they occur.
Is the JSON Diff API free?
Yes. The API is free, needs no key, and can be called from any origin. Requests are rate limited per IP address and request bodies are limited to 1 MB.
What is the difference between a type difference and a value difference?
A value difference means both sides have the same type but different content, such as 1 and 2. A type difference means the types themselves differ, such as the number 1 and the string "1", or an object and an array.
Last updated .