Schema Validity Rules

## Two validations, two moments Almost every confusing GraphQL error message becomes obvious once you know which of two validation passes produced it. **Schema validation** asks: *are these type definitions internally coherent?* It runs once, when the server assembles an executable schema out of SDL text or out of code definitions, before any client exists. Its input is only the schema. **Document validation** asks: *does this operation make sense against that schema?* It runs per request, and it presumes the schema already passed. This leaf is about the first pass. The practical consequence is the failure mode. A document that breaks a rule comes back as a normal HTTP response carrying an `errors` array. A **schema** that breaks a rule produces no response at all: the server cannot construct the thing that would answer, so it throws while wiring up and the process does not reach a listening state. "The service will not start" and "the service returned an error" are different incidents, and the first is a total outage of every operation at once. ## The rules a server checks The specification's type-system section lists validity rules per definition kind. Working in a legal case-file graph, the ones that bite in practice: **Every referenced type must be defined.** A field typed `Docket` when nothing defines `Docket` is not a runtime lookup failure; it is an invalid schema. **Root operation types must be object types,** and a schema must have a query root. A schema whose mutation root is an interface is invalid. **Union members must be object types.** Not interfaces, not other unions, not scalars, not input objects. `union Evidence = Exhibit | Testimony | CaseRecord` is invalid the moment `CaseRecord` is an interface — a union is an open set of concrete alternatives, and members that are themselves abstract would make the runtime type undecidable. **An object type implementing an interface must declare every field that interface declares,** with compatible types and identical argument types, and must also declare every interface that interface itself implements. **Arguments must be input types; fields must return output types.** Scalars and enums sit on both sides of that split, but an object, interface or union may only be a field's *return* type, and an input object may only be an *argument* or input-field type. Declaring `filings(filter: CaseFile): [Filing!]` where `CaseFile` is an object type is invalid — there is no way to write an object type as a literal or a variable value. **Input object fields must be input types,** for the same reason, and an input object that references itself through a chain of non-null, non-list fields is invalid because no finite value could satisfy it. **Names beginning with `__` are reserved** for introspection, so you cannot define `__caseId`. Enum values may not be spelled `true`, `false` or `null`, because those literals already mean something else in a document. ## Why validate once instead of per request Three reasons. Cost: these checks are quadratic-ish over the type graph and would be wasted work on every request. Determinism: an invalid schema is a deployment defect, not a client mistake, and failing loudly at build or startup puts the error in front of the person who caused it. And integrity of everything downstream: introspection results, typed client generators, registries and any tooling that reads the schema all assume a schema that already passed — serving a half-coherent schema would corrupt every consumer rather than one caller. ## Where you find out When the schema is a checked-in SDL artefact, a build step can validate it and fail the pipeline. When the schema is assembled from code definitions at process start, the same rules run then, and you learn on deploy. Either way the fix is the same: get schema validation into continuous integration so an invalid schema never reaches a running environment, because there is no partial degradation available — a schema either builds or the service does not exist. ## What it does not check Schema validation is purely structural. It has no opinion on whether your names are good, whether a change you just made will break an existing client, whether a field is expensive to resolve, or whether a resolver exists for every field. A schema can be perfectly valid and still be a bad contract, and a valid schema can still return errors on every request.