api-shape-diff

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

npx api-shape-diff before.json after.json

Alias:

npx api-shape-diff examples/v1.json examples/v2.json
# or after install: shapediff examples/v1.json examples/v2.json

Example output:

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:

npx api-shape-diff snapshots/user-v1.json snapshots/user-v2.json --fail-on breaking

Generate a pull request note:

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 <n>	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