Compare two JSON documents as data, not as text
Two JSON files that mean the same thing can look very different: one serializer writes keys alphabetically, another in insertion order, one indents with two spaces, the other puts everything on one line. A text diff shows all of that as changes and buries the one value that really differs. This JSON diff parses both documents first and compares the data. A key that moved is not a change, a reindented file is not a change, but a number that became a string is, and it is marked as a type change so you cannot miss it. Typical uses: an API response before and after a deploy, two versions of a config file, a settings export, or the one field a colleague changed in a fixture. For prose and code, use text compare; to clean up a single document, the JSON formatter.
Added, removed, changed and type changes
| Kind | Meaning | Example |
|---|---|---|
| Added | A key or array element exists only in the right document | /user/phone appears on the right |
| Removed | A key or array element exists only in the left document | /user/fax is gone on the right |
| Changed | The same key holds a different value of the same type | /price: 9.5 became 10 |
| Type change | The value turned into another kind of value | /zip: "02134" became 2134 |
| Key order | Same keys in another order (only with Ignore key order off) | /user: name, id became id, name |
Objects are compared key by key, and the comparison continues inside nested objects and arrays, so a change deep inside a document is reported with its full path instead of marking the whole parent as different.
Paths are JSON Pointers
Every difference comes with the path of the value, written as a JSON Pointer as defined in RFC 6901. A pointer is a string of reference tokens, each preceded by a slash: /orders/2/total is the key total of the third element of the array orders. Array indexes are zero-based decimal numbers. Because the slash and the tilde have a meaning in a pointer, a tilde inside a key is written as ~0 and a slash as ~1, so the key a/b becomes /a~1b. The empty string points to the whole document, which is what you see when the root itself changed type, for example from an array to an object.
How arrays are compared
Arrays are ordered, so by default elements are matched in order. The tool finds the longest sequence of elements that both arrays share in the same order, the same idea a line diff uses. Elements outside that sequence are removed or added, and where an element was replaced by another in the same spot, the two are paired and compared further, so a list of records with one edited entry shows the edited field, not a whole removed and added record. An element inserted in the middle of a list is one addition, not a shift of everything after it.
With Ignore array order on, arrays are treated as bags: an element counts as kept when an equal element appears anywhere in the other array. Use this for tags, sets of IDs and other lists where the order carries no meaning. Very long arrays (where the product of both lengths passes 250,000) are matched with a faster forward scan that can miss a match when the arrays differ a lot.
Ignore key order and whitespace
- Ignore key order is on by default. RFC 8259 defines an object as an unordered collection of zero or more name and value pairs, and most parsers give you the same object either way. Turn it off when you compare the byte-for-byte output of two tools; objects with the same keys in another order are then listed under Key order, without changing the other counts.
- Ignore whitespace in strings treats strings as equal when they differ only in spaces, tabs and line breaks, for example a description that was reflowed. Keys are never changed by this option, only values.
The options only change what counts as different; the side-by-side view always shows the values as parsed. JavaScript reads numbers as 64-bit floating point values, so 1.0 and 1 are the same number here, and digits beyond the 17th significant one are not compared.
List, side by side, text and JSON Patch
The List view shows one row per difference: the kind, the path and the old and new value. Side by side prints both documents formatted with two spaces, with the right document's keys in the order of the left one so that lines match up, and marks removed and changed lines on the left and added and changed lines on the right. Copy as text gives you the list as plain lines with a plus for added, a minus for removed, a tilde for changed and an exclamation mark for type changes, ready for a ticket or a code review.
Copy JSON Patch and Download patch produce a JSON Patch document as defined in RFC 6902: a JSON array of operation objects, each with an op and a path, and a value for add and replace. The tool uses only add, remove and replace, ordered so that applying them one after another to the left document gives the right one: removals within an array last index first, then insertions from the start, then changes inside kept elements. The media type is application/json-patch+json.
A worked example
Left: {"name": "Ann", "age": 31, "tags": ["a", "b"], "zip": "02134"}. Right: {"zip": 2134, "age": 32, "name": "Ann", "tags": ["a", "c", "b"], "city": "Boston"}. Four differences: /age changed from 31 to 32, /zip changed type from string to number, "c" was added at /tags/1, and /city was added. The key order differs too, but it is ignored unless you switch that option off. The JSON Patch has two replace and two add operations.
Limits
- Both inputs must be valid JSON. Comments, trailing commas and single quotes are errors, shown with line and column. The JSON formatter can repair such input first.
- Files up to 20 MB can be opened. Very large documents take a few seconds.
- Duplicate keys in one object are parsed the way JavaScript does it: the last value wins.
- Other formats need converting first: YAML to JSON, CSV to JSON. To describe the shape of one document, use JSON to TypeScript.
How to use the JSON diff tool
- 1Paste the old document on the left and the new one on the right, or open a .json file for each.
- 2Set the options: ignore array order for unordered lists, switch key order on if it matters, ignore whitespace in strings if text was reflowed.
- 3Read the counts and the list, switch to Side by side for context, then copy the differences as text or as a JSON Patch.
Sources
- RFC 6901: JavaScript Object Notation (JSON) Pointer
- RFC 6902: JavaScript Object Notation (JSON) Patch
- RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
Related guides
- JSON vs YAML vs CSV: Which Format for Which Job
- JSON Syntax Errors: What Breaks a Parser and How to Fix It
- Semantic Versioning Explained: Major, Minor and Patch
Frequently asked questions
How do I compare two JSON files?
Paste the first document into Left and the second into Right, or open a .json file for each. Both are parsed and compared as data, not as text, so a different key order or indentation does not count. The differences appear right away with their path, and the counts tell you how many values were added, removed or changed.
What is the path shown next to each difference?
It is a JSON Pointer as defined in RFC 6901: a slash for each level, with object keys and array indexes, like /users/0/email. A slash inside a key is written as ~1 and a tilde as ~0. The empty path stands for the whole document.
What is the difference between a changed value and a type change?
A changed value keeps its type, for example the number 1 becoming 2 or one string becoming another. A type change is a value that turned into another kind of value, such as the string "5" becoming the number 5, or null becoming an object. Type changes are easy to miss in a text diff and often break programs, so they are counted separately.
Why does the tool ignore key order by default?
JSON objects are unordered: the JSON standard says an object is an unordered collection of name and value pairs, and most programs that read JSON do not care in which order the keys were written. Switch Ignore key order off if the order matters to you, for example when you compare the output of two serializers, and objects whose keys come in another order are listed too.
What does Ignore array order do?
Arrays are ordered, so by default [1, 2] and [2, 1] differ. With Ignore array order on, an element counts as kept when an equal element appears anywhere in the other array, which is useful for lists of records in no particular order. The JSON Patch then adds new elements at the end of the array and the result holds the same elements as the right document, possibly in another order.
What is the JSON Patch for?
A JSON Patch (RFC 6902) is a list of operations that turns the left document into the right one, using add, remove and replace with a JSON Pointer path each. Many libraries and APIs can apply such a patch. Key order differences have no operation and are left out.
Is my JSON uploaded?
No. Both documents are parsed and compared in your browser. Files you open are read on your device. Copy link only shares the settings, never the documents.