ForgeHub blog

How to compare two JSON files without uploading them

2026-10-15T00:00:00Z

To compare two JSON files without uploading them, use a diff tool that parses and compares the JSON entirely inside your browser tab, such as JSON Mirror, or compare them offline with jq or a few lines of Python. Either way the documents never leave your machine, which matters when they contain API keys, customer records or internal configuration.

Why you shouldn't paste sensitive JSON into any online diff site

The JSON people need to compare is rarely harmless. It is usually one of these:

Configuration files that contain database URLs, API keys, OAuth client secrets or feature flags you have not announced.
API responses that include access tokens, session IDs, or internal identifiers.
Customer data such as names, emails, addresses and order histories: personal data that your privacy policy, contracts or regulations may restrict.

Many hosted "JSON diff online" tools send what you paste to a server, either to compute the diff or to create a shareable link. Once the data is on someone else's server, you cannot see whether it is logged, cached, indexed or kept. For a secret, the safe assumption is that it has been exposed and must be rotated. For personal data, pasting it into an unvetted third-party service may break your organisation's data-handling rules even if nothing bad ever happens to it.

The fix is simple: only use a comparison method where the JSON stays on your device. There are three practical options, described below.

How to compare two JSON documents in your browser, step by step

JSON Mirror is a free JSON diff that runs entirely in the browser tab. There is no account and no install, it makes no network requests while you work, and it uses no analytics, cookies or browser storage. Close the tab and the data is gone.

1. Paste the two documents

Paste the older version into Original and the newer one into Updated. To follow along, press Load example, which fills in these two documents:

{"project":"JSON Mirror","version":"1.0","settings":{"theme":"light","notifications":true},"members":["Alex","Sam"],"status":"draft"}

{"project":"JSON Mirror","version":"1.1","settings":{"theme":"dark","notifications":true},"members":["Alex","Sam","Jordan"],"published":true}

If a document is minified, the Format button pretty-prints that editor. Swap exchanges the two inputs if you pasted them the wrong way round.

2. Press Compare JSON

Click Compare JSON or press Ctrl+Enter (Cmd+Enter on a Mac). JSON Mirror parses both documents and compares their structure, not their text, so whitespace and object key order are ignored. (For why that is the right default, see why key order and whitespace shouldn't show up in a JSON diff.) The example produces five changes:

Kind	Path	Original	Updated
changed	`$.version`	`"1.0"`	`"1.1"`
changed	`$.settings.theme`	`"light"`	`"dark"`
added	`$.members[2]`	(none)	`"Jordan"`
removed	`$.status`	`"draft"`	(none)
added	`$.published`	(none)	`true`

Each entry also carries a one-line plain-English explanation and shows the original and updated values side by side.

3. Filter the results

Use the All / Changed / Added / Removed filter to focus. In the example, Changed shows the two edited values, Added shows the new array item and the new published key, and Removed shows only $.status. The screen lists the first 300 entries per filter.

4. Read the paths

Every path starts at $, the root of the document. Simple keys use dot notation ($.settings.theme), array positions use brackets ($.members[2] is the third item), and unusual keys use quoted brackets, such as $["first name"]. The guide to reading JSON paths in a diff covers the details.

5. Export the report

Export report downloads a JSON report with every entry, not just the first 300, generated in the browser and saved to your machine. If you edit either input after comparing, the results are marked stale and export is disabled until you compare again, so a report always matches the inputs it came from. For what the file contains, see how to export JSON differences beyond the 300-result view.

Know the limits

Arrays are compared by index, so inserting an item near the start shows up as several "changed" entries plus one "added" entry; moves are not detected (see comparing JSON arrays by position or by identity). Numbers are parsed with the standard JavaScript JSON.parse, so integers larger than 9,007,199,254,740,991 can lose precision. Each input is limited to 1,000,000 characters, and nesting deeper than 120 levels is rejected.

How to compare JSON files offline with jq

If you already have jq installed, this one-liner works in bash and zsh:

diff <(jq -S . a.json) <(jq -S . b.json)

jq . pretty-prints each file with consistent indentation, and -S sorts the keys of every object. That normalises both files, so differences in key order and whitespace disappear. diff then compares the two normalised outputs line by line.

Keep in mind that this is still a text diff of the normalised output. It tells you which lines differ, not which JSON paths, and a change deep in a large file is shown with line numbers rather than $.settings.theme. Array order is preserved, so reordered arrays still show up as changes. For a quick check in a terminal or a CI job, it is hard to beat.

How to check whether two JSON files are equal in Python

When you only need a yes or no, Python's standard library is enough:

import json

with open("a.json") as f:
    a = json.load(f)
with open("b.json") as f:
    b = json.load(f)

print("equal" if a == b else "different")

Dictionary comparison ignores key order and list comparison respects position, so == gives the same answer as a structural diff. Python also parses JSON integers exactly, so large IDs compare correctly. What it does not tell you is where the documents differ. For that you would need to write a recursive walk, or use one of the tools above.

Which method should you use?

Method	Best for	Output	Trade-off
JSON Mirror (browser)	Reviewing changes, sharing a report, no tools installed	Kind, path, explanation and values per change	Index-based arrays; large integers may lose precision
`jq -S` + `diff`	Terminals, scripts, CI	Line-based text diff	No JSON paths; needs jq and a shell with process substitution
Python `==`	Automated equality checks, exact big integers	Equal or different	Does not say where the difference is

Checklist: how to tell if a JSON diff tool is really local

"Private" and "secure" on a landing page are claims, not proof. You can check a browser-based tool yourself in a couple of minutes, using dummy data first:

Watch the Network tab. Open DevTools (F12), go to the Network tab, clear it, then paste and compare. A local tool makes no new requests when you compare.
Go offline. Load the page, disconnect from the network, and run a comparison. If it still works, the diff is computed on your device.
Look for share links. A "share" or "save" button that produces a URL to your diff usually means your input is stored on a server.
Check for accounts and trackers. A tool that requires sign-in, or loads analytics and advertising scripts, has more places for data to go.
Read the privacy statement. It should say plainly that input is not uploaded, and that should match what you saw in steps 1 and 2.

Try it

The safest way to compare two JSON files is one where the data never leaves your machine. For a readable, path-by-path report, open JSON Mirror, press Load example, and compare. For scripts and CI, reach for jq -S with diff, or a Python equality check when you only need to know whether anything changed.

Why key order and whitespace shouldn't show up in a JSON diff

2026-10-15T00:00:00Z

Key order and whitespace shouldn't appear in a JSON diff because they aren't part of the data. RFC 8259 defines a JSON object as an unordered collection of name/value pairs and allows insignificant whitespace around structural characters. A text diff still reports them as changes. A structural (semantic) JSON diff parses both documents first, so it reports only real differences in values, types and structure.

What the JSON spec says about key order and whitespace

RFC 8259, the current JSON standard, settles both points:

Key order: "An object is an unordered collection of zero or more name/value pairs." The objects {"a":1,"b":2} and {"b":2,"a":1} hold the same data.
Whitespace: "Insignificant whitespace is allowed before or after any of the six structural characters" ({ } [ ] : ,). That whitespace can be any mix of spaces, tabs, line feeds and carriage returns. Indentation, line breaks, CRLF vs LF and a trailing newline at the end of the file don't change what a JSON document means.

A structural JSON comparison parses each document into values (objects, arrays, strings, numbers, booleans, null) and compares those values. A text diff compares the characters or lines. Most of the confusion in JSON reviews comes from mixing up these two kinds of diff.

Example: a 14-line git diff with zero data changes

Here's a config file stored minified on one line, with no trailing newline:

{"name":"build-agent","id":4182,"enabled":true,"tags":["ci","linux"],"limits":{"memoryMb":8192,"cpu":4}}

Someone opens it in a tool that pretty-prints with two-space indentation, sorts keys alphabetically and adds a final newline. Then they commit it. Here's what git diff shows:

@@ -1 +1,13 @@
-{"name":"build-agent","id":4182,"enabled":true,"tags":["ci","linux"],"limits":{"memoryMb":8192,"cpu":4}}
\ No newline at end of file
+{
+  "enabled": true,
+  "id": 4182,
+  "limits": {
+    "cpu": 4,
+    "memoryMb": 8192
+  },
+  "name": "build-agent",
+  "tags": [
+    "ci",
+    "linux"
+  ]
+}

That's 13 insertions and 1 deletion, and not one value changed. A structural diff of the same two files finds zero changes. Every key and value, and every array position, is identical.

Example: one real change hidden in the noise

Now suppose the same commit also raised the memory limit from 8192 to 16384. git diff --stat reports exactly the same thing as before: 13 insertions(+), 1 deletion(-). The real change is on one of those 13 green lines, and nothing marks it as different from the formatting noise. A reviewer has to compare a 100-character line against 13 reformatted lines in their head.

A structural diff reports one entry:

changed  $.limits.memoryMb   8192 -> 16384

This is the core argument for a semantic JSON diff. When formatting and data change in the same commit, a line diff can't separate them. JSON Mirror compares parsed structure, so this example produces exactly one "changed" entry with its path. (If the path notation is new to you, see Reading JSON paths in a diff.)

Where JSON formatting noise comes from

Serializers that reorder keys

Different tools write the same object in different key orders:

Python's json.dumps(obj, sort_keys=True) sorts keys. Go's encoding/json sorts map keys when it marshals a map.
PostgreSQL's jsonb type doesn't preserve key order or whitespace, so data that goes through it comes back in a different order.
JavaScript objects list integer-like keys first, in ascending order. JSON.stringify(JSON.parse('{"b":1,"10":2,"2":3}')) returns {"2":3,"10":2,"b":1}, even though nobody asked for a reorder.

Pretty-printed vs minified

APIs often return minified JSON, while files in a repository are usually indented. Indent width (2 spaces, 4 spaces, tabs) also differs between editors and formatters. Converting between any of these rewrites nearly every line.

Trailing newline and line endings

JSON.stringify doesn't add a final newline, but many editors and command-line tools do. Git flags the difference with "No newline at end of file", and CRLF vs LF conversion on Windows can touch every line. To a JSON parser, both are insignificant whitespace.

What a structural JSON comparison still treats as meaningful

Ignoring formatting doesn't mean ignoring everything. These differences are real, and a good structural diff reports them:

Array order. Arrays are ordered in JSON, so ["ci","linux"] and ["linux","ci"] are different. JSON Mirror compares arrays by index, so this shows up as two changed entries, $.tags[0] and $.tags[1]. It doesn't detect moves. If your arrays are really sets or lists of records with IDs, read Comparing JSON arrays: by position or by identity?
Types. "1" (a string) and 1 (a number) are different values. Likewise "true" and true. JSON Mirror reports a type change as one change at that path.
Missing vs null. {"a":null} and {} aren't the same document, and JSON Mirror treats them as different.

Number representation subtleties

A JavaScript-based diff parses every number as an IEEE-754 double. That has two consequences:

1.0 and 1 parse to the same number, as do 1e2 and 100, so they compare equal. Usually that's what you want.
Integers beyond 2^53 - 1 (9,007,199,254,740,991) lose precision. JSON.parse("9007199254740993") returns 9007199254740992, so a change between those two values is invisible. For large IDs or exact decimal amounts, compare with a parser that keeps integers exact (Python's json module does) or store such values as strings.

Duplicate keys

RFC 8259 says names within an object SHOULD be unique, but it doesn't forbid duplicates. JSON.parse keeps the last value, so {"a":1,"a":2} parses to {"a":2} and compares equal to it. A text diff would show the duplicate. A structural diff built on JSON.parse won't, so if duplicates might matter in your data, check for them separately.

Text diff vs structural diff

Difference between the two files	Text diff (e.g. git diff)	Structural diff
Indentation, spaces, line breaks	Changed lines	Ignored
Minified vs pretty-printed	Almost every line changed	Ignored
Object key order	Changed lines	Ignored
Trailing newline, CRLF vs LF	Flagged	Ignored
A changed value	A changed line, possibly buried in noise	One entry with its path
Array items reordered	Changed lines	Changed entries (when compared by index)
`"1"` vs `1`	Changed line	Type change
`1.0` vs `1`	Changed line	Equal (same parsed number)
Integers beyond 2^53 - 1	Changed line	May be missed by double-based parsers
Duplicate keys	Visible	Collapsed to the last value
Invalid JSON	Still diffs the text	Can't compare until it parses

How to make git diff ignore JSON key order and whitespace

If you want to keep using git for review, normalize both versions before comparing. jq -S . re-indents the document and sorts object keys recursively:

diff <(jq -S . before.json) <(jq -S . after.json)

To make git diff do this automatically, add a textconv filter. In .gitattributes:

*.json diff=json

Then configure the filter:

git config diff.json.textconv "jq -S ."

Git now shows diffs of the normalized output, while the files in the repository stay unchanged. A few caveats apply. A file that isn't valid JSON makes jq fail, so the diff fails too. Array order is still compared line by line. And jq doesn't necessarily normalize how a number is written, so 1.0 vs 1 may still appear. Older jq versions (before 1.7) also convert numbers to doubles, which brings back the large-integer problem.

A short script works too. In Python, json.load(f1) == json.load(f2) ignores key order and whitespace and keeps large integers exact. One caveat: Python treats True == 1 and 1 == 1.0 as equal, so [true] and [1] would compare equal.

Try a structural JSON diff

A JSON diff should answer one question: what changed in the data? Key order, indentation and trailing newlines don't affect the data, so they shouldn't take up space in the result. Array order, types, null vs missing, and changed values do, so they should.

To see this on your own files, paste both versions into JSON Mirror. It ignores whitespace and key order, lists each change with its path, and runs entirely in your browser, so nothing is uploaded. For large integers or arrays where position isn't meaningful, use the alternatives above.

null vs. missing: the JSON difference that breaks APIs

2026-10-15T00:00:00Z

In JSON, {"nickname": null} and {} are not the same document. The first says "this field exists and has no value"; the second says nothing about the field at all. APIs routinely treat them differently, most visibly in PATCH requests and JSON Merge Patch, where null means "delete this field" and a missing key means "leave it alone", so any tool that compares JSON must keep the two cases apart.

This post explains where the difference matters, the JavaScript and serializer habits that blur it, and how JSON Mirror reports each case when you diff two documents.

What null and a missing key mean in JSON

JSON, as defined in RFC 8259, has six kinds of value: object, array, string, number, the literals true and false, and the literal null. There is no undefined.

Explicit null: the key is present in the object and its value is null. Object.keys lists it; the document is one member larger.
Missing key: the key is absent. The document makes no statement about it.

Whether those two states mean different things is up to the API. But because they can mean different things, a parser, a serializer, or a diff that silently converts one into the other is changing the message.

JSON Merge Patch: null means remove

The clearest example is JSON Merge Patch, specified in RFC 7396 and sent with the media type application/merge-patch+json. A merge patch looks like a partial copy of the resource, and the rules are short:

A member with a non-null value in the patch replaces (or adds) that member in the target. Nested objects are merged recursively.
A member set to null in the patch removes that member from the target.
A member that is absent from the patch is left unchanged.

Given this stored user:

{"name": "Alex", "nickname": "Al", "email": "alex@example.com"}

these three patches do three different things:

{}                     -> nothing changes
{"nickname": "Lex"}    -> nickname becomes "Lex"
{"nickname": null}     -> nickname is deleted:
                          {"name": "Alex", "email": "alex@example.com"}

One consequence the RFC itself points out: merge patch is a poor fit for documents that rely on explicit null values, because you cannot use it to set a member to null. Arrays are also replaced wholesale rather than edited. If you need either of those, JSON Patch (RFC 6902) uses explicit add, remove and replace operations instead.

PATCH endpoints and partial updates

Plenty of PATCH endpoints follow the same convention without formally implementing RFC 7396: send only the fields you want to change, send null to clear a field. That convention only works if every layer between the client and the database preserves the difference between "absent" and "null". Common ways it breaks:

The server deserializes the body into a typed object where a missing field and a null field both end up as null. The handler then clears every field the client did not send.
The client builds the body from a form model and serializes every property, so untouched fields go out as null and wipe stored data.
The client's serializer is configured to omit nulls, so a deliberate "clear this field" request arrives as an empty object and does nothing.

The fix on the server side is usually to inspect the raw JSON tree for key presence (for example Jackson's JsonNode.has("nickname"), or 'nickname' in body in Python) before mapping it into a model.

JSON null vs undefined in JavaScript

JavaScript has two "empty" values, and the language's own operators make it easy to merge them by accident:

const missing = JSON.parse('{}');
const isNull  = JSON.parse('{"nickname": null}');

missing.nickname === undefined;     // true
isNull.nickname === undefined;      // false (it is null)

missing.nickname == null;           // true
isNull.nickname == null;            // true  (null == undefined is true)

'nickname' in missing;              // false
Object.hasOwn(isNull, 'nickname');  // true

Things to remember:

obj.key === undefined is true both when the key is missing and when it exists with the value undefined. It cannot tell you whether the key is there.
null == undefined is true, so a loose == null check treats null and missing identically. null === undefined is false.
JSON.stringify drops object properties whose value is undefined: JSON.stringify({nickname: undefined}) produces {}, while JSON.stringify({nickname: null}) produces {"nickname":null}. (Inside arrays, undefined becomes null.)
To test for presence, use Object.hasOwn(obj, 'key') or 'key' in obj. The in operator also looks up the prototype chain, which rarely matters for parsed JSON but is worth knowing.

So if you want a JavaScript client to send "clear this field", set it to null. If you want "leave it alone", delete the property or never set it; undefined also works, but only because JSON.stringify happens to drop it.

Serializers that omit null fields

Many JSON serializers have an option to omit null fields from the output, often to make payloads smaller. In Java's Jackson, for example, annotating a class or property with @JsonInclude(JsonInclude.Include.NON_NULL) leaves null-valued properties out entirely.

That setting is harmless for read-only responses where clients treat null and missing the same way. It is risky for:

request bodies sent to a PATCH or merge-patch endpoint, where null carries meaning;
responses whose consumers check for key presence, such as schemas with required-but-nullable fields;
snapshot or contract tests, where flipping the setting changes every fixture at once.

If you change a serializer setting like this, diff a before and after payload to see exactly which keys appeared or disappeared.

How a JSON diff should report null vs missing

A diff that treats null and missing as equal will hide exactly the changes described above. JSON Mirror checks key presence first and compares values second, so each case gets its own entry. Here is what it reports for the field $.nickname:

Original	Updated	Kind	Explanation shown
`{}`	`{"nickname": null}`	added (value `null`)	This value exists only in the updated document.
`{"nickname": null}`	`{}`	removed (value `null`)	This value was removed from the original document.
`{"nickname": null}`	`{"nickname": "Sam"}`	changed	The value type changed from null to string.
`{"nickname": "Sam"}`	`{"nickname": null}`	changed	The value type changed from string to null.

Two points worth noting:

An added or removed null is still a real change. If an API response starts including "nickname": null where it used to omit the key, that shows up as an added entry, not as "no difference".
Going from null to a value is a changed entry with a type change, because null is its own JSON type. Comparing {"nickname": null} with {"nickname": null} reports nothing.

Key order and whitespace are ignored, so only presence and value differences appear; see why key order and whitespace shouldn't show up in a JSON diff. Paths such as $.nickname are explained in reading JSON paths in a diff.

Checking null vs missing without a diff tool

If you only need to check one field, a one-liner is enough. In jq, .nickname returns null for both cases, so use has:

jq 'has("nickname")' user.json

In Python, d.get("nickname") returns None for both, while "nickname" in d tells them apart:

import json
d = json.loads('{"nickname": null}')
print("nickname" in d, d.get("nickname"))   # True None

For whole documents, a structural diff is easier than writing these checks by hand.

Try it

Paste a request body before and after a serializer change, or an API response from two releases, into JSON Mirror and press Compare JSON. Keys that went from missing to null, or from null to missing, appear as separate added and removed entries, each with its path and both values side by side. Everything runs in your browser tab and nothing is uploaded.

Comparing JSON arrays: by position or by identity?

2026-10-15T00:00:00Z

There are four common ways to diff JSON arrays: by index (position 0 against position 0), by an identity key (match objects by a field such as id), by sequence alignment (the longest-common-subsequence approach line diffs use), and as an unordered set. Comparing by index is the simplest and most predictable, but one item inserted at the front makes every later position look changed. If order does not matter in your data, sort both arrays by a stable key before comparing, or turn them into objects keyed by id.

Why arrays are the hard part of a JSON diff

Objects are easy to diff because members have names. $.settings.theme in one document clearly corresponds to $.settings.theme in the other, and key order is irrelevant (see why key order and whitespace shouldn't show up in a JSON diff).

Array elements have no names, only positions. RFC 8259 defines an array as an ordered sequence of values, so order is part of the data. But many real arrays, such as a list of users, tags or permissions, are really collections where order is incidental. A diff tool has to decide which element in the original corresponds to which element in the updated document, and that decision is the whole difference between the strategies below.

The example: one item inserted at the front

Every strategy below uses the same pair of documents. The only real change is that a new user was added at the start of the array.

// before.json
{"users": [
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"},
  {"id": 3, "name": "Linus"}
]}

// after.json
{"users": [
  {"id": 4, "name": "Margaret"},
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"},
  {"id": 3, "name": "Linus"}
]}

A human reads this as "one user added". Whether a tool agrees depends on how it matches elements.

Comparing JSON arrays by index (position)

How it works: element [0] is compared with element [0], [1] with [1], and so on. If the updated array is longer, the extra positions are reported as added; if it is shorter, the missing positions are reported as removed. Objects inside the array are compared field by field.

This is the strategy JSON Mirror uses. For the example above it reports seven entries:

changed  $.users[0].id     1 -> 4
changed  $.users[0].name   "Ada" -> "Margaret"
changed  $.users[1].id     2 -> 1
changed  $.users[1].name   "Grace" -> "Ada"
changed  $.users[2].id     3 -> 2
changed  $.users[2].name   "Linus" -> "Grace"
added    $.users[3]        {"id": 3, "name": "Linus"}

Every later position reports a change, and the last original element reappears as an "added" entry at the end. Nothing here is wrong: position 0 really did hold Ada and now holds Margaret. It is just not the summary a person wants.

Why it is still a reasonable default: it is predictable. Every path in the output points at a real location in both documents, so you can look up $.users[2] in either input and see exactly the values shown (more on that in reading JSON paths in a diff). It needs no configuration, no schema knowledge and no heuristics, the same input always produces the same output, and it runs in linear time. Appends and in-place edits, which are very common, produce clean results.

Limitations: inserts and deletes near the start cause a cascade of "changed" noise, and it does not detect moves. Swapping two items reports changes at both positions.

Diffing arrays of objects by id (identity key)

How it works: you name a field that uniquely identifies each element, such as id, sku or email. The tool matches elements with the same key value regardless of position, then compares matched pairs field by field. Keys present only in the updated array are added; keys present only in the original are removed.

For the example, the result is a single entry, shown here in illustrative notation:

added    users[id=4]   {"id": 4, "name": "Margaret"}

Pros: the output matches human intent, moves are ignored, and an edited user is reported as a change to that user rather than to a position. With a hash map it is roughly linear in cost.

Cons: it needs schema-specific knowledge, so a generic tool has to be told which key to use, and different arrays in one document may need different keys. Keys must be present and unique; duplicate or missing ids silently merge or drop elements. It does not apply to arrays of plain values like ["a", "b"], and it hides reordering, which matters if order is meaningful (a priority list, for instance).

Sequence alignment: how line diffs handle arrays

How it works: the tool finds the longest common subsequence (LCS) of elements that are exactly equal in both arrays, then reports everything outside it as inserted or deleted. Myers' algorithm, used by git diff and GNU diff, is an efficient way to compute this kind of minimal edit script.

You can see it on the example by printing one array element per line and running an ordinary line diff:

diff <(jq -cS '.users[]' before.json) <(jq -cS '.users[]' after.json)

0a1
> {"id":4,"name":"Margaret"}

One insertion before the first line: the right answer, with no key required.

Pros: it handles inserts and deletes anywhere without a schema, and preserves order information.

Cons: matching uses exact equality, so an element that was both moved and edited appears as one deletion plus one insertion. Reordering also shows up as delete/insert pairs rather than moves. It costs more: classic LCS is O(n × m), and Myers is O((n + m) × D), where D is the size of the difference, which is fast for small changes but slows down for very different arrays. When several alignments are equally short, which one is chosen depends on the implementation.

Comparing JSON arrays as a set (ignore order)

How it works: each array is treated as an unordered collection (strictly, a multiset if duplicates count). Elements that appear in both are ignored; the rest are reported as added or removed. The example again produces one "added" entry for Margaret.

Pros: no key needed, and order differences disappear entirely. It is a good fit for tags, roles and permission lists.

Cons: an edited element is reported as one removal plus one addition, with no field-level detail. Real order changes become invisible, and you must decide whether duplicates matter.

JSON array diff strategies compared

Strategy	Matches elements by	Front insertion in the example	Needs a key?	Typical cost	Main drawback
By index	Position	6 changed + 1 added	No	Linear	Cascading "changed" noise; no move detection
By identity key	A field such as `id`	1 added	Yes, unique and present	Roughly linear (hashing)	Schema-specific; hides reordering
Sequence alignment (LCS / Myers)	Longest run of equal elements	1 inserted at [0]	No	O(n × m), or O((n + m) × D)	Edited + moved items become delete + insert
As a set (ignore order)	Equal values anywhere	1 added	No	O(n log n) sort or hashing	Edits become remove + add; order is lost

No strategy is best everywhere. Index comparison is the most predictable, identity keys give the most readable output when you have a reliable key, and set comparison is right only when order genuinely carries no meaning.

Practical tips for a cleaner JSON array diff

Sort arrays before comparing when order is not meaningful

Normalizing both documents turns an index-based diff into an order-insensitive one. For a top-level array of objects:

jq 'sort_by(.id)' before.json > before.sorted.json
jq 'sort_by(.id)' after.json  > after.sorted.json

For an array nested inside a document, update it in place; -S also sorts object keys, which helps if you will use a text diff afterwards:

jq -S '.users |= sort_by(.id)' before.json > before.sorted.json

After sorting, the example produces a single entry in an index-based diff: added $.users[3] with Margaret's record. For arrays of plain values, use jq 'sort'.

Compare keyed maps instead of arrays

If elements have a unique id, converting the array to an object gives you identity matching in any tool that diffs objects. In jq 1.6 or later:

jq '.users |= INDEX(.id)' before.json > before.keyed.json

This produces {"users": {"1": {...}, "2": {...}, "3": {...}}}, and the diff path for the new user becomes $.users["4"]. The same idea in Python:

import json

def by_id(path):
    with open(path) as f:
        return {u["id"]: u for u in json.load(f)["users"]}

old, new = by_id("before.json"), by_id("after.json")
print("added:", sorted(new.keys() - old.keys()))
print("removed:", sorted(old.keys() - new.keys()))
print("changed:", sorted(k for k in old.keys() & new.keys() if old[k] != new[k]))

Check for duplicate ids first; with either approach, a later element with the same id overwrites an earlier one.

Append rather than prepend in fixtures

If you control the data, such as test fixtures, snapshot files or seed data, add new items at the end. Appends produce exactly one "added" entry in an index-based diff, so reviews stay short and unrelated entries do not churn.

Try it

Paste the two documents from this article into JSON Mirror to see index-based comparison in action, then sort both by id with jq and compare again to watch seven entries collapse to one. Everything runs in your browser tab, and nothing you paste is uploaded. If your arrays are collections rather than sequences, normalize them first; if order matters, a position-based diff tells you exactly what is at each index.

Reading JSON paths in a diff: $.settings.theme, $.members[2] and friends

2026-10-15T00:00:00Z

A JSON path in a diff tells you exactly where a change happened. $ is the root of the document, .name steps into an object key, [2] steps into an array at a zero-based index, and ["odd key"] is used when a key is not a simple identifier. So $.members[2] means "the third item of the members array at the top level".

This guide explains the notation as it appears in JSON Mirror and most other JSON diff tools, shows how it maps to JSON Pointer, jq, JavaScript and Python, and how to jump from a path in a report straight to the value in your own data.

What a JSON diff path looks like

Take this pair of documents:

// Original
{"project":"JSON Mirror","version":"1.0","settings":{"theme":"light","notifications":true},"members":["Alex","Sam"],"status":"draft"}

// Updated
{"project":"JSON Mirror","version":"1.1","settings":{"theme":"dark","notifications":true},"members":["Alex","Sam","Jordan"],"published":true}

Comparing them produces five changes, each identified by a path:

changed $.version: "1.0" became "1.1"
changed $.settings.theme: "light" became "dark"
added $.members[2]: "Jordan"
removed $.status
added $.published: true

Read each path left to right as a set of directions: start at the root, then follow each step. $.settings.theme means "root, then key settings, then key theme".

The $ root symbol

The $ comes from JSONPath, a query notation that has been used informally for years and was standardized as RFC 9535 in February 2024. In JSONPath, $ is the root node: the entire parsed document.

If the whole document is a single primitive, such as 42 or "hello", there is nothing to step into. A change from 42 to 43 is reported at the path $ alone. The same happens when the top-level type changes, for example from an object to an array: it is one change at $.

Dot notation vs. bracket notation

Paths use three kinds of step.

Dot notation for identifier-like keys

$.settings.theme is the readable form for ordinary keys. JSON Mirror uses a dot only when the key matches the regular expression /^[A-Za-z_$][\w$]*$/: a letter, underscore or dollar sign, followed by letters, digits, underscores or dollar signs. That covers $.user_id, $.createdAt and $.$ref.

Bracket index notation for arrays

Array elements are addressed by position in square brackets, counting from zero. $.members[0] is "Alex", $.members[1] is "Sam", and $.members[2] is "Jordan". Steps chain naturally: $.orders[0].items[3].sku.

One caution: an index is a position, not an identity. JSON Mirror compares arrays by index, so inserting an item near the start shifts every later element and can produce several "changed" entries plus one "added" at the end. If your arrays hold records with IDs, read Comparing JSON arrays: by position or by identity? before trusting index paths.

Quoted bracket notation for unusual keys

Any key that fails the identifier test is written as a quoted string inside brackets. That includes keys with:

spaces: $["first name"]
dashes: $["first-name"]
dots: $["a.b"] (this is one key named a.b, not key b inside key a)
a leading digit: $["2fa"]
an empty name: the key "" becomes $[""]

The quoted part uses JSON string escaping, so a key containing a double quote appears as $["say \"hi\""]. The distinction between $["a.b"] and $.a.b is the main reason brackets exist: without them, the two paths would look identical.

A note on strictness: RFC 9535's dot shorthand allows letters, digits, underscores and non-ASCII characters, but not $. If you paste a path like $.$ref into a strict JSONPath implementation, write it as $["$ref"] instead. The bracket form is always valid.

JSONPath vs. JSON Pointer

JSON Pointer (RFC 6901) is the other common way to address a value. It is what JSON Schema $ref fragments and JSON Patch operations use. The differences:

JSONPath is a query language; it can also express wildcards and filters. A diff only uses its simplest form, a single concrete location.
JSON Pointer identifies exactly one value. The root is the empty string "", and each step is a / followed by a key or index: /members/2.
JSON Pointer has no quoting. Instead, ~ in a key is written ~0 and / is written ~1. A key named a/b is /a~1b.
Array indexes are zero-based in both.

Because JSON Pointer does not use dots as separators, keys like a.b or first-name need no special treatment: /a.b, /first-name.

Translation table: JSONPath, JSON Pointer, jq, JavaScript, Python

The same locations in each notation. data is the parsed document.

Diff path (JSONPath)	JSON Pointer	jq	JavaScript	Python
`$`	`""` (empty)	`.`	`data`	`data`
`$.settings.theme`	`/settings/theme`	`.settings.theme`	`data.settings.theme`	`data["settings"]["theme"]`
`$.members[2]`	`/members/2`	`.members[2]`	`data.members[2]`	`data["members"][2]`
`$["first-name"]`	`/first-name`	`.["first-name"]`	`data["first-name"]`	`data["first-name"]`
`$["a.b"]`	`/a.b`	`.["a.b"]`	`data["a.b"]`	`data["a.b"]`
`$["a/b"]`	`/a~1b`	`.["a/b"]`	`data["a/b"]`	`data["a/b"]`
`$[""]`	`/`	`.[""]`	`data[""]`	`data[""]`
`$.$ref`	`/$ref`	`.["$ref"]`	`data.$ref`	`data["$ref"]`

Two rows deserve a second look. The JSON Pointer / is not the root; it points to the key named "", because the root pointer is the empty string. And in jq, $ starts a variable name, so a key like $ref needs the bracket form.

How to jump from a diff path to the value

Once a diff has told you where something changed, you often want to look at the surrounding data or check the value in another file. Translate the path one step at a time.

With jq

jq paths look almost identical to JSONPath; drop the leading $:

jq '.members[2]' updated.json
"Jordan"

jq '.settings' original.json
{
  "theme": "light",
  "notifications": true
}

jq '.["first-name"]' user.json

The single quotes above are for POSIX shells such as bash and zsh; other shells may need different quoting.

With JavaScript

const data = JSON.parse(text);
data.settings.theme;    // "dark"
data.members[2];        // "Jordan"
data["first-name"];     // bracket form for unusual keys

Since JSON Mirror's dot rule follows JavaScript identifier syntax for ASCII keys, any path it prints can be pasted after data by replacing the $.

With Python

import json

with open("updated.json") as f:
    data = json.load(f)

data["settings"]["theme"]   # 'dark'
data["members"][2]          # 'Jordan'

Python has no dot access for dictionaries, so every key step becomes ["key"] and every index step stays [n].

Reading paths on added and removed entries

The path of an "added" entry exists only in the updated document; the path of a "removed" entry exists only in the original. Running jq '.status' updated.json on the example above prints null, because jq returns null for a missing key. That is easy to misread: a missing key and an explicit null are different things, and JSON Mirror reports them differently. null vs. missing: the JSON difference that breaks APIs covers why that matters. In jq, has("status") tells the two apart.

When a whole object or array is added or removed, the diff shows one entry at the subtree's path containing the full value, rather than one entry per nested key.

Try it

Paste two versions of a document into JSON Mirror and every change comes back with its path, a one-line explanation and the before and after values. Everything runs in your browser tab, and nothing is uploaded. Use the table above to turn any path into a jq filter or a line of code, and remember the two rules that trip people up most: indexes start at zero, and quoted brackets mean "this is one key, read it literally".

How to Export JSON Differences Beyond the 300-Result View

2026-10-15T00:00:00Z

The 300-result limit in JSON Mirror applies to the visible list, not to the exported report. After a successful comparison, Export report downloads the complete changes array. Choose the right original and updated documents, compare them again after any edit, and use the JSON file when you need every recorded difference.

Open JSON Mirror

The visible list and the report serve different purposes

JSON Mirror keeps the comparison result in memory as a changes array. Its screen renderer selects the current filter and draws only the first 300 matching entries. If more matches exist, a notice explains that the list is shortened and directs you to export the report. That notice describes a display boundary; it does not mean that comparison stopped after finding 300 differences.

For example, a comparison with 305 added values can display 300 cards while the downloaded report still contains all 305 changes. Use the filters to inspect particular kinds of differences, and use the export when a later review needs the full recorded set. The app does not currently offer pagination through every result card.

Compare the intended inputs before exporting

Put the earlier document in Original and the later document in Updated, then select Compare JSON. The direction matters because the result describes additions and removals relative to those two inputs. If you swap them, compare again before exporting. The report should represent the comparison you actually intend to share or inspect.

Editing either input after a comparison makes the displayed result stale. JSON Mirror disables the export control and asks you to compare again. Do not treat an older visible list as evidence that your latest edits were compared. Complete another successful comparison first; validation or comparison errors also leave exporting disabled.

Know what the downloaded file contains

Export report creates a JSON download named json-mirror-report.json. Its top-level data identifies the tool, records that array comparison is by index, and includes the in-memory report with a comparison timestamp and changes. The export handler uses that report directly rather than exporting just the currently selected screen filter.

This distinction matters when you inspect only Added or Removed on screen. A filter helps you browse the comparison, but it does not turn the downloaded file into a filtered report. If another workflow requires only one change kind, inspect the downloaded changes array and select the relevant records in that workflow. JSON Mirror does not provide that separate export option.

Understand the limits an export does not remove

A complete export means the complete result of a successful comparison, not unlimited input support. Each editor has a one-million-character input limit. Comparisons may also fail when the supported nesting depth is exceeded. Exporting cannot bypass those checks or recover a comparison that never completed.

The arrayComparison field is a reminder of another boundary: arrays are compared by index. A moved or inserted item can therefore produce several position-based differences. The downloaded file preserves that interpretation; it does not independently detect moves or match objects by an identity field. Read those changes in the context of your data.

Keep a report only when your workflow needs it

The app builds the download from a browser Blob when you choose Export report. This lets you decide when to create a file instead of treating every comparison as something to retain. Once you download or share the report, handle it according to the sensitivity of the values it contains. A local tool does not make a shared output harmless.

For a repeatable review, confirm the input direction, run a fresh successful comparison, note any shortened-list notice, and download the report. Check that the changes array is the result you expected before passing the file onward. The comparedAt timestamp records when that comparison was made; it is not proof that the source documents are current.

AI-assisted ForgeHub editorial. App capabilities were checked against its implementation; this guide is not an independent review.