Your GraphQL schema renamed a field and broke a shipped mobile release — how should that rename have been rolled out?

## Why a rename hurts more than it looks like it should Intuition says removing one field costs you one field. In GraphQL it costs you every document that mentioned it. Selecting a field that is not defined on the type is a **validation error** — a request error, raised before execution begins. The specification is explicit that when a request fails before execution, the response does not carry a `data` entry at all. So the client does not get its other eleven fields with one hole in them; it gets an error list and nothing else. In the incident that prompts this question, the statements screen of mobile build 4.9 sent a single document selecting twelve fields on `Statement`, one of them `closingBalance`. The rename deployed at 09:14 and the screen was blank for every user on 4.9 — 61% of installs that morning — with roughly 4,800 rejected operations in the first eighteen minutes. No amount of client-side cleverness helps: an alias renames the response key, not the schema field, so clients cannot alias their way around a field that no longer exists. And a shipped binary cannot be redeployed; the only fix available to the server team was to put the old field back. ```json { "errors": [ { "message": "Field 'closingBalance' is not defined by type 'Statement'.", "locations": [{ "line": 4, "column": 5 }] } ] } ``` (The exact message text is up to the implementation; what is specified is that this is a request error and that `data` is absent.) ## Expand: add before you subtract The pattern is the same expand–migrate–contract shape used for database columns, applied to a schema. Add `endingBalance` next to `closingBalance` and ship that alone. It is a pure addition: no deployed document selects the new name, so nothing changes for anyone. Now the graph can answer to both names for as long as it needs to. The important detail is that both fields must resolve from **one source of truth**. Two resolvers computing "the balance" independently will drift the first time somebody fixes rounding on one of them, and then you have two fields with the same name-ish meaning and different values — a far worse failure than the rename, because it is silent. ```pseudocode resolve Statement.endingBalance(statement): return statement.balances.closing # the deprecated spelling delegates - no second code path, no drift resolve Statement.closingBalance(statement): return resolve Statement.endingBalance(statement) ``` ## Migrate: make the mark do work Mark the old field with `@deprecated` and put something useful in the reason. "No longer supported" — the directive's default — tells a client engineer nothing. `@deprecated(reason: "Renamed; use endingBalance. Removal after 2026-11-30.")` names the replacement and the deadline, and that string is what shows up in an explorer, in generated types and in editor tooltips. Deprecated members also drop out of the default introspection listing, so a new screen written next month is unlikely to pick the dying name by accident. What the mark does not do is anything at runtime. Every existing document keeps working unchanged, which is exactly the property you want: the deprecation is an announcement, not an outage. ## Contract: removal is a separate, evidenced piece of work Removal is where the discipline actually lives, and it needs two inputs. First, evidence that no live client selects the field — which is a matter of recorded field usage over a window long enough to cover infrequent screens, and is its own topic. Second, a deliberate check of the proposed schema against the published one before it merges, which is likewise its own topic. The point to make in an interview is that removal is scheduled work with a gate in front of it, not an opportunistic tidy-up while you are in the file. ## When the rename is not really a rename Distinguish two cases, because they get very different treatment. A **cosmetic** rename — same value, better name — has real cost and modest benefit: you carry two spellings for months, generated types get noisier, and the 37-field `Statement` briefly becomes a 38-field one. It is sometimes still worth it, but be honest that clarity is the whole return. A **semantic** change dressed as a rename is the opposite: if `endingBalance` means something different from what `closingBalance` meant, then the new name is doing essential work, because keeping the old name and quietly changing its meaning would break every consumer silently, with nothing to diff and nothing to validate. In that case the deprecation reason should say what changed, not just where to go. The rule that falls out of both: in a versionless graph, additions are cheap, removals are scheduled, and in-place edits to something a client already names are the one move that has no safe form.