# JSON Diff

> Semantic diff between two JSON documents reported by JSON path — added, removed, changed with old/new values, recursing nested objects and comparing arrays positionally. Use when `diff` on JSON is useless (key reordering, formatting noise), for config drift checks, API response comparison, or CI gates on expected output.

- Skill: `trac3r00/json-diff` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add trac3r00/json-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/trac3r00/json-diff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: trac3r00 (https://skillmd.com/u/trac3r00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/trac3r00/json-diff

---


# JSON Diff

`diff` on JSON is useless — one reordered key and everything flags. This
parses both documents and reports what actually changed, by path.

## Commands

```bash
python3 scripts/json_diff.py old.json new.json
python3 scripts/json_diff.py a.json b.json --json
python3 scripts/json_diff.py expected.json actual.json --max-changes 0
curl -s api/v1/config | python3 scripts/json_diff.py - prod-config.json
```

## Output

```
~ port: 8080 -> 9090
+ db.ssl: true
- legacy_mode: false
~ tags: array[2] -> array[3]
```

Paths use dot notation for objects (`db.host`) and brackets for arrays
(`items[2]`). `--max-changes N` makes it a CI gate: exit 1 when the count
exceeds N (use 0 for "must be identical").

## Pairs with

`env-gate` (config completeness), `api-tester` (fetch the JSON this diffs),
`verification-before-completion` (the discipline that makes you run it).