Schema Linting

## Two gates, and only one of them can stop the server Every GraphQL server runs a schema through one mandatory check before it will serve a request. The specification calls it type-system validation, and it asks structural questions with yes-or-no answers: does the query root type exist and is it an object type; does every object type declare at least one field; does a type that claims to implement an interface declare every one of that interface's fields with a compatible type and compatible arguments; are field names unique within a type; does every type named in a field or argument position actually exist; is every directive applied in a location its definition permits, and applied once where the definition is not repeatable. Fail any of these and there is no schema. The server refuses to build it, and there is nothing to lint because there is nothing to serve. That is a different check from validating an operation a client sends. Document validation happens per request, against a schema that is already known good. Schema linting is neither: it is a build-time opinion about a schema that has passed the first gate and would happily serve traffic. ## What is left for the linter Everything a linter flags is, by construction, legal. The specification is deliberately quiet about a large surface, and a linter fills that silence with a team's decisions. The four rules most commonly seen in the wild are all in this category: - **A description on every publicly reachable field.** Descriptions in SDL are string literals written before a definition, exposed to consumers through introspection's `description` field. The specification requires none of them anywhere. - **A real `reason` on every `@deprecated`.** The built-in directive defines `reason` with a default, so bare `@deprecated` is legal and produces a string that tells a consumer nothing. - **No nullable item type inside a list.** `[Leg]` permits a null in every element slot. `[Leg!]` does not. Both are valid; only one of them is what almost every author meant. - **No type unreachable from the root operation types.** A type that no field returns and no union or interface admits is still a type. It is still shipped through introspection to every consumer. ```graphql # Every line here passes type-system validation. type Query { shipment(id: ID!): Shipment } type Shipment { id: ID! legs: [Leg] # lint: a null may appear in any element slot carrierCode: String @deprecated # lint: no reason argument given } type Leg { id: ID! arrivedAt: String # lint: no description on a public field } type CarrierManifest { # lint: no root field can reach this type id: ID! sealNumber: String! } ``` A freight-tracking graph that shipped exactly this SDL would run. Every consumer of it would also inherit four small, permanent taxes: a null-check per leg, a deprecation notice with no forwarding address, an undocumented timestamp field of unstated timezone and format, and a type in the generated client that nothing can ever return. ## Why the distinction is itself the interview question A great deal of what people call "GraphQL" is convention. Connections and cursors, global object identification, persisted documents, cost limits, and every rule in this list are widespread practice, not specified requirements. Candidates who cannot separate the two make two characteristic mistakes. They assert that the specification forbids something it permits, which makes every downstream claim suspect. And they treat a lint failure as a correctness failure, which leads to arguing about a nullable item type as though the schema were broken rather than as a tradeoff with a real counterargument. The useful framing is about who pays. A validity failure is paid by the team that wrote it, immediately, at startup. A lint violation is paid by everyone downstream, slowly: the consumer reading undocumented field, the generated client carrying an optional it never needed, the team that deletes a deprecated field and discovers nobody was told what to move to. Linting exists because none of those people are in the pull request. ## What linting cannot see A linter reads the SDL and nothing else. It can check that a description exists; it cannot check that the description is true, current, or useful. It can check that a `reason` string is present and not the default; it cannot check that the replacement it names exists. It can check the shape of a type modifier; it cannot tell whether a nullable field is a considered decision or an oversight. It knows nothing about behaviour, authorization, resolver cost, or whether the mutation you added is the right granularity. A clean lint run is a floor. It is evidence that the obvious mechanical conventions hold, and it is not evidence of design quality — which is why teams pair it with schema review rather than replacing review with it.