This JSON changed. Could it break a client?

• Missing, null and a type change are different things

  A side that doesn't exist is absent, not null. Every difference is classed breaking, additive or data, so a reviewer knows what to look at first.

• Exact numbers

  Integers beyond 2^53 stay exact, and 1, 1.0 and 1e0 are equal. JSON.parse would round the first and can't tell the others apart.

• Redaction that holds

  Listed paths never appear in text, JSON, added subtrees or errors. No hashes either, since hashes of weak secrets can be brute-forced.

• Array order is your call

  Ordered by default. Switch a path to unordered, or key it by a field like sku, and reordering stops being noise.

• Schema diagnostics

  Optional Ajv-backed validation that explains what's wrong without echoing the document's values.

• Built for CI

  Exit codes 0, 1 and 2, stable sorted JSON, stdin support and a plain-JSON config that rejects typos. Zero runtime dependencies.

Paths are not redacted: object keys appear in them. Read the redaction guarantees and limits →

1. 1

   Diff two files

   Use - to read one side from stdin. Exit codes tell your pipeline what happened.

   sh

   m2jsonlens diff baseline.json candidate.json --config m2jsonlens.config.json
   curl -s $URL | m2jsonlens diff golden.json -      # "-" reads one side from stdin
   m2jsonlens validate response.json --schema orders.schema.json

2. 2

   Keep the rules in a config

   Plain JSON, never code. Unknown keys are errors, so typos are caught.

   json

   {
     "ignore": ["/requestId", "**/updatedAt"],
     "redact": ["/order/auth/token", "/order/customer/email"],
     "arrays": {
       "default": "ordered",
       "rules": [
         { "path": "/order/items", "mode": "keyed", "key": "sku" },
         { "path": "/order/tags", "mode": "unordered" }
       ]
     },
     "failOn": "breaking"
   }

3. 3

   Or call the library

   The result is plain data you can filter and test. ESM and CommonJS are both shipped.

   ts

   import { compare, formatText, parseJson } from "m2jsonlens";
   
   declare const baselineText: string;
   declare const candidateText: string;
   
   const result = compare(parseJson(baselineText), parseJson(candidateText), {
     ignore: ["/requestId"],
     redact: ["/auth/token"],
     arrays: { rules: [{ path: "/items", mode: "keyed", key: "sku" }] },
   });
   
   if (result.summary.breaking > 0) console.error(formatText(result));

   yaml

   - run: npm ci
   - run: npx m2jsonlens diff golden.json <(curl -s $URL) --config m2jsonlens.config.json --fail-on breaking

• ignorePaths excluded from comparison. * matches one segment, ** matches any number.
• redactPaths whose values never appear anywhere in the output. Nothing is guessed.
• arrays: orderedThe default. Array order is significant unless a rule says otherwise.
• arrays: unorderedElements match as a multiset, duplicates counted.
• arrays: keyedElements match by a field such as sku, and diff at field level.
• --fail-onany, breaking or none: decides which differences make the exit code non-zero.

See the full semantics →