Schema Checks & Registries

## Why the check exists at all GraphQL ships one endpoint and one schema, and the specification gives you nothing to protect it. There is no version in the URL, no content negotiation, no compatibility rule a server enforces at start-up. If you delete a field, the server starts happily and every client that still selects it starts getting a **validation error on the whole request** — not a missing key, a rejected document. The only thing standing between an edit and that outcome is a process you build yourself. A schema check is that process, expressed as a CI step. So the first thing to say in an interview is the honest one: *schema checks are a tooling convention.* The specification does not define them, does not define a registry, and does not define the verdict names. Anyone who tells you "the spec classifies changes as breaking" is wrong. ## The two inputs **The proposed schema** — the schema this branch would publish if it merged. For a schema-first project that is the SDL after all files are combined; for a code-first project it is the executable schema the built server produces, printed back out. The check must take the *whole* resulting schema, not a `git diff` of one file, because an edit to a shared type or a code-generated fragment shows up nowhere in the file you touched. **The baseline** — the schema currently published for the environment the change is heading to, fetched from a schema registry. This is the half people get wrong; it is not the SDL on your main branch, and it is not the file you started from. ## Structural, not textual Both sides are parsed into type systems and walked: types, fields, arguments, input fields, enum values, union members, interface implementations, default values, and the nullability and list wrappers on each. Textual diffing would be useless — moving a type into another file, alphabetising fields, or rewrapping a description all produce large diffs and zero semantic change, and a gate that fires on those loses its audience within a week. ## The three verdicts Names vary between tools, but the common shape is three-way, and the interesting question is *why three rather than two*. * **Safe / non-breaking** — no currently valid operation can behave differently. Adding a field to an object type, adding an optional argument, adding a whole new type, editing a description. * **Breaking** — an operation that was valid becomes invalid, or a promise the schema made is withdrawn. Removing or renaming a field is the obvious member of this class. * **Dangerous** — the edit cannot invalidate any existing document, yet consumer code can still mishandle what comes back. Adding a value to an enum that appears in a response is the canonical example: every document stays valid, and a client that switches exhaustively over the members meets a value nobody handled. Adding a member to a union, adding a new implementation of an interface, and changing an argument's default value sit in the same class. A two-way split would force all of those into "safe", where nothing looks at them. The middle class exists so a human sees them. ## A worked diff Take a parcel-locker graph. The published baseline has `enum CompartmentSize { SMALL MEDIUM LARGE }`, a `Compartment.size: CompartmentSize!`, and a long-deprecated `Compartment.sizeCode: String`. The branch adds `OVERSIZE` to the enum, adds `Compartment.heightMm: Int`, and finally deletes `sizeCode`. The check reports three edits: `heightMm` **safe**, `OVERSIZE` **dangerous**, `sizeCode` **breaking**. That output is a list, not a decision — the *gate* is the policy layered on top, and the policy is where teams differ. And the dangerous line is not theoretical. The kiosk firmware on the locker banks switched exhaustively over `CompartmentSize` and fell into its default branch when it first saw `OVERSIZE`, refusing drop-offs at those banks until the fleet was patched. No document was invalid; nothing in the type system had been withdrawn. ## What the check cannot tell you **It reasons about possibility, not reality.** "Breaking" means *some* valid document could select the removed field — not that any client does. Recorded usage is the separate signal that turns "could" into "did" or "did not", and a gate without it either blocks every removal forever or waves them all through. **It sees types, not meaning.** Changing the units a field returns, the default ordering of a list, the encoding of an opaque cursor, or the validation a resolver applies to an argument leaves the type system byte-identical. A structural diff reports nothing, and a team that treats a green check as proof of compatibility has bought false confidence in exactly the cases it cannot see.