Deprecating Fields Safely

A Deprecation Is a Runway, Not a Switch

GraphQL has one endpoint and no URL to version. When a field disappears, every client still selecting it gets an execution error — including mobile builds you cannot patch, partner integrations on quarterly releases, and a dashboard nobody has opened since last year.

So a graph evolves differently from a REST resource: a field is never removed in the release that replaces it. There is a runway, and each stage has a gate:

@deprecated is deliberately weak: the field stays fully executable, so nothing breaks while you measure. Its force is on tooling — GraphiQL and Explorer strike the field through, code generators warn or stop emitting it, and introspection exposes isDeprecated and deprecationReason to anything that asks.

type Order {
  "Prefer `total`; it includes tax and shipping."
  subtotal: Int! @deprecated(reason: "Use total. Removal planned for 2026-06-01.")
  total: Int!
}

The alternative — remove first, apologize later — is what makes teams afraid to touch their own schema. A predictable runway is why a well-maintained graph can change weekly without a version number: clients can plan because the contract includes how change happens, not just what the fields are named.

The runway also has a floor. A field deprecated with no removal date is a suggestion, and suggestions rot: within a year half the schema carries strikethrough and nobody knows which names are safe to build on.

Writing Reasons Clients Can Act On

A deprecation without a reason is a dead end: the client learns something is wrong and cannot act. The reason string is the only channel you have, because it travels through introspection to code you have never seen.

• Bad: "Deprecated" — names no replacement and no date.
• Better: "Use total instead" — actionable, still incomplete: which semantic difference, and when does it break?
• Good: "Use total (includes tax and shipping). Removal planned 2026-06-01; see docs.example.com/orders/migration." — replacement, difference, date, and a place to read more.

Deprecation reaches further than object fields:

enum ShipmentStatus {
  PENDING IN_TRANSIT DELIVERED
  CANCELLED @deprecated(reason: "Use FAILED with reason CANCELLED_BY_CUSTOMER.")
}

input OrderFilter {
  status: ShipmentStatus
  "Matches a single instant only; prefer createdAt with a DateRange."
  shippedOn: Date @deprecated(reason: "Use createdAt: DateRange. Removal 2026-06-01.")
}

Enum values and input fields deserve the same care as fields. A value that vanishes from an enum breaks every client that still sends it in a variable, so annotate it in the release that introduces the replacement rather than at removal time. The reason should also state the semantic difference whenever the replacement is not a one-to-one swap — a client that swaps CANCELLED for FAILED without reading the note will silently change what its UI shows.

Clients discover it through introspection

{
  __type(name: "Order") {
    fields { name isDeprecated deprecationReason }
  }
}

Any client can enumerate every deprecated field in one request — which means a partner can build a report and a reviewer can hold your removal to the date you published. That accountability is the point of writing reasons carefully: you are writing to an audience you cannot talk to directly, and the string outlives the pull request that added it.

Fields with reasons also show up in schema reviews and generated documentation, so a precise reason doubles as the migration guide for the small, common case where a client just needs to know what to type instead.

Measuring Before You Remove

Stage three is the one teams skip, and it is the only stage that tells you whether removal is safe. The measurement has two halves: which documents still mention the field, and which of those documents real clients actually send.

const usage = new Map(); // field name -> { documents: Set, clients: Set }

const deprecatedUsagePlugin = {
  onExecute({ document, contextValue }) {
    visit(document, {
      Field(node) {
        const name = node.name.value;
        if (!DEPRECATED.has(name)) return;
        const entry = usage.get(name) || { documents: new Set(), clients: new Set() };
        entry.documents.add(hashDocument(document));
        entry.clients.add(contextValue.clientId || 'anonymous');
        usage.set(name, entry);
      },
    });
  },
};

Counting document occurrences is cheap and runs on every request; tagging the client id tells you whether those selections come from your own web app — redeployable today — or from a partner integration that ships quarterly. When persisted queries are in use, the query id maps straight to a named client, which makes the report trivial and the conversation short.

Sizing the sunset window

• Internal consumers: two weeks plus a changelog entry is usually enough.
• Public API or partners: 30-90 days, announced by email and by response headers where you can add them.
• Mobile apps you do not control: the oldest app version you still support plus app-store review lag — often a full quarter.

Remove only once the count of distinct external clients selecting the field has been zero for a complete window, and remove in one release with a breaking-change note, following the same rules as any other removal in schema evolution rules.

The failure on the other side

Deprecating and never removing is its own bug: a schema where half the fields are struck through, so the strikethrough stops meaning anything. Track a deprecated-fields report the way you track flaky tests — a count that only goes down — and give every annotation a removal date on the day you write it. Data plus a deadline is what keeps a runway from becoming a parking lot.