How do you set a schema deprecation policy for a GraphQL API whose oldest clients are shipped mobile apps?

## Why this is a policy problem and not an engineering one In a versioned API you can freeze a shape and let it rot in place; the old contract keeps its own address and its own lifetime. A versionless graph has no such compartment. One schema serves the internal reporting job, the web app, the partner integration and a mobile build from fourteen months ago, simultaneously. `@deprecated` is the only carve-out mechanism the specification gives you, and it is purely advisory — nothing stops a client from selecting a deprecated field, and nothing forces you to ever remove one. Everything that makes deprecation mean something is organisational. ## Start by classifying consumers by upgrade control The useful axis is not "internal versus external" but **can I cause this client to change?** - **Callers you deploy**: batch jobs, other services, server-rendered pages. Days to weeks, and you can often do the migration for them. - **Callers a user reloads**: a web bundle. Hours to days, bounded by cache and long-lived sessions. - **Callers a user installs**: shipped mobile binaries. Months, with a long tail you do not control, and a floor set by however many people never update at all. On a statements graph, the third class is the one that sets policy. If build 4.9 is on 61% of installs the morning you deprecate, the question is not "how long is reasonable" but "what does the install-age curve look like at the 99th percentile, and where does it flatten". That number is measurable, and it is the honest input to the window. ## Turn the mark into a commitment A deprecation that says only `@deprecated(reason: "No longer supported")` is a shrug. A deprecation that is a commitment carries four things: the **replacement** (what do I write instead), the **date** (when does this stop resolving), an **owner** (who is accountable for the removal, tracked wherever the team tracks work), and a **gate** (what evidence must exist before the field is deleted). The evidence and the mechanical check are separate disciplines — recorded field usage over a window long enough to cover monthly and quarterly screens, and a diff of the proposed schema against the published one in the pipeline — but the policy is what says they are required. The date belongs in the reason string as well as in the tracker, because the reason string is the only part of the migration that reaches a client engineer reading a generated type at 11pm. ## Fund the contraction, or deprecation stops meaning anything The failure mode that shows up in real graphs is not premature removal; it is removal that never happens. Marks accumulate. A `Statement` type reaches 37 fields, eleven of them deprecated, four of them alternative spellings of the same money value. The costs are diffuse and real: generated client types carry the dead members, every explorer session needs a second look with `includeDeprecated: true` to understand history, onboarding engineers cannot tell which of three balance fields is canonical, and each retained field is still a live, resolvable, supportable path with its own backend calls and its own authorization surface. So the policy needs a contraction budget — a standing slot for finishing removals — and a rule that a new deprecation without a date is not accepted. Otherwise the org has quietly chosen the worst combination available: no version boundary and no cleanup. ## Levers when the window is not affordable Sometimes waiting out the install base is not an option — a field leaks data it should not, or a regulator requires it gone. The levers, roughly in order of preference: - **Minimum supported client**: refuse very old builds at the transport and prompt an upgrade. This is a blunt, visible break, but it is a break you schedule and communicate rather than one that surprises you. - **Degrade before deleting**: make the field nullable and return null. Old documents stay valid, one value goes blank instead of a whole screen. It buys a smaller failure, not a free one, and it only works while nothing non-null depends on it. - **Behaviour keyed to the caller**: possible, and mostly a trap. It re-introduces per-client contracts inside a single schema, which is precisely the thing one graph was supposed to eliminate, and it makes the schema stop describing what a client actually gets. ## When a real version is the honest answer Occasionally the change is not a field but a whole domain model, and dripping it out field-by-field would take years. The lower-cost form of that is a **parallel type family inside the same schema** — new types, new root fields, old ones deprecated en masse — rather than a second endpoint. You keep one registry, one set of tooling, one authorization model and one operational surface, and you accept a temporary, dated duplication. A second endpoint doubles the operational and governance story and should be reserved for the case where the two graphs genuinely serve different audiences. ## What to say out loud in the interview Name the tradeoff rather than the number. Every additional week of deprecation window is a week of dual maintenance and dual truth; every week you cut is somebody's broken app. A strict policy fails loudly and rarely, a lax one fails quietly and permanently, and the job of the policy is to make that choice deliberate and visible rather than an accident of who was on call.