graphql‑sdl‑diff

What this tool does — and its honest limits

What it does. graphql-sdl-diff compares two GraphQL SDL strings and returns a flat, classified changelog: every change graded breaking, dangerous, review or safe, ready to paste into a pull request. It answers the question every schema change raises — “will this break my clients?” — the same way a CI gate or a schema-registry pre-flight check would, but instantly and locally. The parser and the core breaking/dangerous taxonomy come from a pinned, vendored copy of the reference graphql-js (16.11.0, MIT); this tool is the honest classification layer on top, not a from-scratch GraphQL implementation.

The conservative rail. The classifier never emits a false safe: anything it cannot prove backward-compatible is graded dangerous or routed to “review manually”, never quietly downgraded. Directive and custom-scalar changes are always flagged rather than resolved — a directive’s runtime effect (auth, rate limiting, formatting…) lives in your executor, outside the SDL, so no type-only diff can judge it. One subtlety worth knowing: merely non-breaking relaxations — an input field going String! → String, an output field going String → String! — report as no change, not safe; only added types, added output fields and noted @deprecated changes earn the safe grade.

Honest limits. It diffs two complete SDL strings — it does not stitch multiple .graphql files for you, and it does not resolve Apollo Federation directives (@key, @external, …), so feed it the already-composed schema text. And like every schema differ, it detects type-system breakage only: a field that keeps its type but changes its meaning is invisible here.