https://github.com/funnyhcat-dotcom/api-shape-diff
Compare JSON/API response shapes and highlight breaking changes.
https://github.com/funnyhcat-dotcom/api-shape-diff
api cli developer-tools diff json nodejs schema testing
Last synced: 7 days ago
JSON representation
Compare JSON/API response shapes and highlight breaking changes.
- Host: GitHub
- URL: https://github.com/funnyhcat-dotcom/api-shape-diff
- Owner: funnyhcat-dotcom
- License: mit
- Created: 2026-06-28T22:35:45.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-06-28T22:35:51.000Z (7 days ago)
- Last Synced: 2026-06-29T00:06:05.773Z (7 days ago)
- Topics: api, cli, developer-tools, diff, json, nodejs, schema, testing
- Language: JavaScript
- Size: 8.79 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# api-shape-diff
[](https://github.com/funnyhcat-dotcom/api-shape-diff/actions/workflows/ci.yml)
[](LICENSE)
Compare two JSON/API responses and see what changed in the **shape**: removed fields, added fields, and type changes.
It is built for developers who want a tiny CLI to catch accidental API breaking changes before they ship.
## Why
API responses drift over time. A field disappears, an `id` changes from number to string, an array item loses a property, and frontends break. `api-shape-diff` gives you a fast sanity check from real JSON samples.
## Try it
```bash
npx api-shape-diff before.json after.json
```
Alias:
```bash
npx api-shape-diff examples/v1.json examples/v2.json
# or after install: shapediff examples/v1.json examples/v2.json
```
Example output:
```text
API shape diff: 8 changes (4 breaking, 4 non-breaking)
! breaking $.email removed $.email
! breaking $.id type changed from number to string
+ non-breaking $.createdAt added $.createdAt
```
## CI usage
Fail a build when a new response sample has breaking changes:
```bash
npx api-shape-diff snapshots/user-v1.json snapshots/user-v2.json --fail-on breaking
```
Generate a pull request note:
```bash
npx api-shape-diff before.json after.json --format markdown > API_DIFF.md
```
## Options
| Option | Description |
|---|---|
| `--format text\|json\|markdown` | Output format. Default: `text` |
| `--fail-on none\|breaking\|any` | Exit non-zero for breaking or any change |
| `--array-mode sample\|all` | Infer arrays from first item or all items. Default: `all` |
| `--max-examples ` | Keep example values in JSON output |
## What counts as breaking?
- Removed fields
- Type changes, such as `number -> string`
- A field becoming required inside mixed array object samples
What is usually non-breaking:
- Added fields
- A field becoming optional
## Limitations
This is not a full JSON Schema validator. It intentionally compares shapes from real JSON samples, so it is simple and fast. For production contracts, pair it with schema tests.
## License
MIT