Skip to content
API Design Learn/GraphQL at Scale
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Evolving a Schema Safely

4 min read

You'll learn to

  • -Phase out a field with @deprecated and keep it working in the meantime
  • -Sort schema changes into additive and breaking, including the enum caveat
  • -Use field-usage data, not the calendar, to decide when a removal is safe

GraphQL has its own version of the REST versioning problem. A schema must evolve, but existing clients cannot all be forced to update on the day a change ships. Unlike REST's habit of putting versions in the URL, GraphQL leans toward evolving one continuously updated schema instead of keeping /v1 and /v2 schemas side by side.

An Analogy: Renaming a Street

When a town renames a street, the old signs stay up for a while, the post office keeps delivering to the old name, and a notice says "this will stop on 1 December". Nobody removes the old name on the first day. And before they finally do, the post office checks whether anyone is still sending mail to the old address. That is deprecation, and it is also field-usage data.

The @deprecated Directive

Marking a field deprecated without removing it
type User {
  id: ID!
  name: String!
  fullName: String! @deprecated(reason: "Use `name` instead. Will be removed 2026-12-01.")
}

@deprecated marks a field as discouraged but keeps it fully working. Existing clients that query fullName carry on, while schema-aware tools, such as editors, documentation generators and linters, show a warning to anyone writing new queries against it. The reason should name the replacement and, where possible, give a concrete removal date: the "why" and the "by when".

Additive vs. Breaking, in GraphQL Terms

  • -Additive, safe: adding a new field, adding a new type, adding a new optional argument to a field, adding a value to an enum (with the caveat below).
  • -Breaking: removing a field, renaming a field, changing a field from nullable to non-null, changing a field's return type, removing an argument.

Adding an enum value deserves its own warning. It is additive from the schema's point of view, but it can still break a client whose code lists the old values and has no default case. The second half of the demo shows exactly that: a client that handles PENDING, SHIPPED and DELIVERED meets a new REFUNDED and fails. "Additive" does not always mean "risk-free".

Field Usage Data: Knowing When Removal Is Safe

A deprecated field cannot be removed just because it was marked deprecated a while ago. The real safety signal is whether any client still queries it. Field-level usage analytics, such as which deprecated fields are still queried, by how many clients and how often, turn "has it been long enough?" into a verifiable question. A deprecated field with zero real traffic over a meaningful window is safe to remove. One that still receives traffic is not, however long ago it was deprecated.

Press Run: fullName still has users, then none after migration; and a new enum value breaks one client

Removing a deprecated field on a fixed schedule without checking usage is an avoidable way to break a client that simply had not got round to migrating. Deprecation is a way to communicate, not a guarantee that migration happened.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Schema Evolution in the API Design Lab's GraphQL Mastery act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!