The example

A (before)

{
  "orderId": "A-1001",
  "status": "paid",
  "updatedAt": "2026-10-20T09:30:00Z",
  "items": [
    { "sku": "BK-001", "qty": 2, "price": 12.5 },
    { "sku": "PN-114", "qty": 1, "price": 3.99 }
  ]
}

B (after)

{
  "status": "paid",
  "orderId": "A-1001",
  "items": [
    { "sku": "PN-114", "qty": 1, "price": "3.99" },
    { "sku": "BK-001", "qty": 3, "price": 12.5 }
  ],
  "updatedAt": "2026-10-21T14:02:11Z"
}

Between A and B, the keys were reordered, the two items swapped places, and the timestamp moved. If we're checking the business data while ignoring timestamps and item order, two changes matter:

1. BK-001's quantity went from 2 to 3.
2. PN-114's price became the string "3.99" instead of the number 3.99, even though it looks the same when printed. That type change can break validation, fail strict equality checks, or cause unexpected results in calculations: "3.99" * 2 is still 7.98, but "3.99" + 1 is the string "3.991".

What a text diff reports

diff a.json b.json flags 5 of A's 11 lines and 6 of B's:

2d1
<   "orderId": "A-1001",
4c3
<   "updatedAt": "2026-10-20T09:30:00Z",
---
>   "orderId": "A-1001",
6,8c5,8
<     { "sku": "BK-001", "qty": 2, "price": 12.5 },
<     { "sku": "PN-114", "qty": 1, "price": 3.99 }
<   ]
---
>     { "sku": "PN-114", "qty": 1, "price": "3.99" },
>     { "sku": "BK-001", "qty": 3, "price": 12.5 }
>   ],
>   "updatedAt": "2026-10-21T14:02:11Z"

The type change is in there, but you have to spot that one pair of quotes among the moved lines.

Sorting keys before diffing is a common next step. It fixes the key order, but the swapped array items still show up as a block of removed and added lines (excerpt):

   "items": [
     {
-      "price": 12.5,
-      "qty": 2,
-      "sku": "BK-001"
-    },
-    {
-      "price": 3.99,
+      "price": "3.99",
       "qty": 1,
       "sku": "PN-114"
+    },
+    {
+      "price": 12.5,
+      "qty": 3,
+      "sku": "BK-001"
     }
   ],

Text tools compare lines. To get a useful answer you need to compare values.

A structural comparison

The function below parses nothing itself. You give it two values from JSON.parse, and it returns a list of changes with their paths. It makes three decisions:

• Objects are compared by key, so key order never matters.
• Arrays are matched by an id field when you configure one for that path, and by position otherwise.
• A value whose type changes (number to string, object to null) is reported as type, separately from an ordinary changed value.

// Structural JSON comparison: key order never matters, arrays are matched
// by an id field when one is configured for that path, otherwise by position.
const kind = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);

function compare(a, b, opts = {}, path = '$', out = []) {
  const { ignore = [], arrayKeys = {} } = opts;
  const name = path.split(/[.[]/).pop();
  if (ignore.includes(name)) return out;

  const ka = kind(a), kb = kind(b);
  if (ka !== kb) {
    out.push({ path, change: 'type', from: a, to: b });
  } else if (ka === 'object') {
    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
      const p = `${path}.${key}`;
      if (!Object.hasOwn(b, key)) out.push({ path: p, change: 'removed', from: a[key] });
      else if (!Object.hasOwn(a, key)) out.push({ path: p, change: 'added', to: b[key] });
      else compare(a[key], b[key], opts, p, out);
    }
  } else if (ka === 'array') {
    const id = arrayKeys[path];
    const index = (list) => {
      const map = new Map();
      list.forEach((item, i) => {
        const k = id ? item?.[id] : i;
        if (k === undefined) throw new Error(`${path}[${i}] has no ${id}`);
        if (map.has(k)) throw new Error(`${path}: duplicate ${id} ${k}`);
        map.set(k, item);
      });
      return map;
    };
    const ma = index(a), mb = index(b);
    for (const k of new Set([...ma.keys(), ...mb.keys()])) {
      const p = id ? `${path}[${id}=${JSON.stringify(k)}]` : `${path}[${k}]`;
      if (!mb.has(k)) out.push({ path: p, change: 'removed', from: ma.get(k) });
      else if (!ma.has(k)) out.push({ path: p, change: 'added', to: mb.get(k) });
      else compare(ma.get(k), mb.get(k), opts, p, out);
    }
  } else if (a !== b) {
    out.push({ path, change: 'changed', from: a, to: b });
  }
  return out;
}

The key checks use Object.hasOwn rather than in, because in also finds inherited properties: with in, a key named toString that exists only in A would be compared against Object.prototype.toString instead of being reported as removed. JSON objects can contain keys like that.

To run the examples, paste the function into a browser console or a Node REPL, then assign the two documents above to a and b. JSON objects are also valid JavaScript object literals, so const a = { "orderId": "A-1001", … } with the full text of A works, and the same for B.

Results on the example

By position, nothing ignored: compare(a, b) returns 7 changes. Key order no longer counts, but because the items swapped places, every field of both items looks different:

Even the type change is reported against the wrong item.

Matched by sku, timestamp ignored:

compare(a, b, { ignore: ['updatedAt'], arrayKeys: { '$.items': 'sku' } });

Those are exactly the two real changes.

Choosing how to match each array

No single rule fits every array, which is why arrayKeys is set per path:

The function above doesn't do the third mode. A starting point is to sort both arrays by a canonical string of each element before comparing them by position. Sorting alone isn't true set semantics, though: if a value appears twice in one array and once in the other, you still need a rule for whether that's a change. Don't apply "ignore order" to a whole document: it hides real changes in any array where order matters.

Edge cases worth deciding on

Records without the id, or with a duplicate id. Matching by key needs every record to have a unique id. The function throws instead of guessing:

$.items[1] has no sku
$.items: duplicate sku 1

A more forgiving version could fall back to position for those records, but say so in the output.

An id that changes. The id is how records are paired, so if a record's sku itself changes, the function reports one record removed and another added, not an id change. That's a reasonable rule, but it means the id field has to be stable as well as unique.

Missing versus null. These aren't the same change, and clients often treat them differently:

compare({ x: 1, y: 2 }, { x: null });
// [ { path: '$.x', change: 'type', from: 1, to: null },
//   { path: '$.y', change: 'removed', from: 2 } ]

Ignored names apply at every depth. ignore: ['updatedAt'] matches by field name, so it also skips updatedAt inside each item. That's usually what you want for timestamps, request ids and ETags. If you need to ignore one specific location, match on the full path instead.

Large integers are lost before you compare. JavaScript can silently round large JSON integers: JSON.parse rounds integers above 2^53, so two different 64-bit IDs can compare as equal:

compare(JSON.parse('{"user": {"id": 9007199254740993}}'),
        JSON.parse('{"user": {"id": 9007199254740992}}'));
// []

If your responses carry IDs that large, parse them with a lossless parser, or compare the IDs as strings.

Takeaways

• Compare parsed values, not lines. That alone removes key-order and whitespace noise.
• Decide per array whether position matters. For records with ids, match by the id.
• Report type changes separately. They're often contract breaks, not data changes.
• Ignore fields that change on every call, by name or by path.
• Watch out for numbers above 2^53 when parsing with JSON.parse.

Compare JSON responses without writing a diff function

If you need to compare two API responses quickly, try CurlyJSON's JSON Diff. Paste the two documents from this article and compare them in your browser. It detects common record identifiers such as id, uuid and sku, labels type changes separately, and supports wildcard patterns for ignoring fields. It also keeps large numbers exact, so it avoids the precision loss that JSON.parse causes. Neither response is uploaded.

The function above is useful when you need custom comparison logic in your own code. CurlyJSON is useful when you just need to see what changed.

Written with AI assistance. Every code sample was run in Node 23, and the outputs shown are the actual results.