Compare API responses and quickly spot field, type, and value changes.
JSON Shape Diff is a dependency-free JSON comparison tool for the browser and CLI. It runs locally and does not upload or store your data.
Requires Node.js 22 or newer. No npm install step is needed.
npm startOpen the local URL printed by the terminal, paste two JSON documents, or click Load sample / 载入示例. The default port is 4173. If you are running multiple tools at once, choose another port:
$env:PORT = '42832'
npm startThe app is served through a local HTTP server. Opening the HTML file directly through file:// is not supported.
- Reports added fields, removed fields, and type changes.
- Can optionally compare concrete string, number, boolean, and null values.
- Supports objects, arrays, and scalar JSON roots.
- Accepts pasted JSON or local files.
- Swaps the two sides and exports Markdown or JSON reports.
- Ignores selected JSON Pointer paths and their descendants, such as
/meta/requestIdor/updatedAt. - Clears stale reports after input changes so old exports are not reused accidentally.
- Renders only a bounded preview in the browser while exports keep the complete report.
| Case | Behavior |
|---|---|
1 to 2 |
Reported only when value comparison is enabled |
1 to "1" |
Reported as a type change |
null to {} |
Reported as a type change |
| Object key order changes | Not reported |
| A whole object is added | Reported once at that object path |
| Array changes | Compared by index; moves and IDs are not inferred |
Paths use JSON Pointer. /user/id means a nested field, / means a field with an empty string as its key, and "" means the root value. Field names encode / as ~1 and ~ as ~0.
Ignored paths filter reported diff paths. If a parent object is added, removed, or changes type, that parent change is still reported even if some of its descendants would be ignored.
node bin/cli.mjs examples/before.json examples/after.json
node bin/cli.mjs examples/before.json examples/after.json --values --format json
node bin/cli.mjs examples/before.json examples/after.json --values --ignore /meta/requestId
node bin/cli.mjs examples/before.json examples/after.json -o report.md
node bin/cli.mjs examples/before.json examples/after.json --check--ignore can be repeated and accepts JSON Pointer paths. --check is useful for automation: exit code 2 means differences were found, 0 means no differences, and 1 means input or execution failed. Output files are never overwritten.
- Each input is limited to 5 MB.
- Comparison stops at 100,000 nodes, 100 levels of nesting, or 5,000 reported changes.
- The browser view renders the first 300 changes and previews up to 5,000 characters per side; exports include the full report.
- Array insertion or movement may produce multiple positional changes.
- JavaScript JSON parsing is used, so duplicate keys follow last-value-wins semantics and numbers use IEEE 754 precision.
- Reports may contain source values. Share only data you are comfortable exposing.
npm testThe browser app and CLI share dist/core.mjs. Tests cover structure mode, value mode, scalar roots, JSON Pointer escaping, arrays, prototype keys, invalid input, depth limits, Markdown fences, and ignored paths.
dist/ is hand-written static source and can be hosted as a static site. This repository does not publish a hosted production site.
See validation notes and contributing notes.
- Match array items by a selected ID field.
- Add wildcard ignore paths for fields repeated inside arrays.
- Export a compact review summary for CI comments.