Versionless Evolution

## Why versions exist at all A version number is a way of saying "the shape of this response changed and I had no way to change it under you." In an endpoint-shaped API the server owns the response body. Drop a key, rename it, or nest it one level deeper, and every caller sees the new body the next time it calls. Since you cannot edit code running on someone else's device, you publish the new body at a new address and keep the old address serving the old one until it is safe to switch it off. GraphQL removes the premise rather than solving the problem. A GraphQL response is assembled from the selection set of the document the client sent: for every field the client named, the server puts one key in the response object, and it puts nothing else there. Two clients hitting the same schema on the same afternoon get different response shapes because they asked different questions. A field the schema gained yesterday is not named in a document written last year, so it cannot appear in that client's response, and that client never needs to learn it exists. ## What the specification actually says about versioning Nothing. The GraphQL specification defines a type system, a document grammar, validation rules and an execution algorithm. It has no notion of a schema version, no version argument, no version header, and no prohibition on running a second endpoint beside the first. Versionless evolution is an ecosystem norm that field selection makes cheap — describe it as a convention in an interview, because calling it a rule is a small but very visible error. The one thing the specification does contribute is the built-in `@deprecated` directive, which gives the convention a vocabulary for "this is on its way out." ## The additive default, concretely Take a bank statements graph. `Statement` is born with an id, a period and a closing balance. Over the following year it acquires interest breakdowns, dispute counts, delivery channels, regulatory flags and a paging argument on its transactions field, until the type carries 37 fields. ```graphql scalar Date scalar Money type Statement { id: ID! periodStart: Date! periodEnd: Date! closingBalance: Money! interestAccrued: Money disputeCount: Int! } type Query { statement(id: ID!): Statement } ``` Every release in that year did one of a small set of things: added a field to an existing type, added a whole type, added an optional argument with a default, added a root field. None of them changed the name, the type or the meaning of a field a live document already selects. A mobile build shipped eleven months ago selects six of the 37 fields and still receives exactly six keys back, in the order it asked for them. It was never redeployed and never needed to be. ## Where "additive is safe" stops being automatic Additive is the default, not a guarantee, and classifying which edits are genuinely safe is a discipline of its own. Two things are worth holding onto at this level. First, the safety argument rests entirely on clients not selecting the new thing — so anything a client is forced to encounter is not covered by it. Second, a change that keeps a field's name and its type but changes what the value *means* is invisible to every diffing tool and every generated type: if `balance` quietly starts meaning the balance at period end rather than the balance right now, nothing anywhere breaks, and every consumer is silently wrong. Versionless evolution has no answer for that, which is why the rule of thumb is to give a new meaning a new field name rather than reuse an old one. ## The other half of the bargain: retire, do not delete If you can only add, the schema grows forever unless something lets you wind fields down. That something is `@deprecated(reason: "...")`, a type-system directive you attach in the schema. It is advisory: a deprecated field is still valid to select and still executes normally. What it does is mark the member for humans and tooling, and hide it from the default introspection listing so new work does not pick it up by accident. Removal is a separate, later act, gated on the field genuinely having no callers left. ## What versionless costs The trade is real. A version cut gives you one coordinated flag day and then a clean schema. Versionless evolution gives you no flag day, and in exchange a permanent low-grade obligation: carry both spellings of anything you rename for as long as an un-upgradable client needs, and actually finish removals rather than letting the schema fill with tombstones. Teams that mark fields deprecated and never remove them get the worst of both worlds — no version boundary and no cleanup — and end up with a type nobody can read.