GraphQL schema versioning strategy
Handling schema evolution, deprecation, and client migrations.
GraphQL's schema flexibility is a blessing and a curse: you can evolve the schema without breaking clients, but if you're not careful, old and new code coexist indefinitely, creating technical debt. This template maps the decision tree every API team faces: when you need to change the schema, which path do you take—add-and-deprecate (safe, gradual) or break-and-migrate (immediate, risky)?
The key insight is that most schema changes don't need versioning at all. Adding fields, types, and enum values is backward-compatible by definition—old clients simply ignore what they don't use. Only removals, narrowing, and mandatory-field additions are breaking; those require either a deprecation grace period or a major-version split.
When to use this template
- API design reviews — agree on your versioning policy before the first breaking change surprises you. Is deprecation grace period 3 months or 12? When do you sunset old versions? Document it here.
- Schema evolution planning — before removing or changing a field, trace through this diagram to decide: deprecate-and-wait, or parallel-versions?
- Client migration communication — send this diagram to consuming teams along with the deprecation notice. It explains why you're sunsetting the old field and gives them a clear path forward.
How to adapt it
Customize the timeline and version strategy to your context:
- Add monitoring steps after each decision: "Check deprecated-field query volume" or "Email teams with 30 days left to migrate" to operationalize the deprecation process.
- Insert parallel-version cost decision: if supporting two major versions is expensive, tighten deprecation timelines or consider a hard cutover date.
- Add client communication nodes: when do you notify consumers? Send emails? Post in Slack? Build the notification cadence into the graph.
Visual edits regenerate clean code, so you can tailor the strategy to your API contracts and team's migration capacity without syntax overhead.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[Need to change schema] --> B{Breaking change?}
B -->|No| C[Add new field or type]
C --> D[Mark old field deprecated]
D --> E[Clients migrate gradually]
E --> F{Clients ready?}
F -->|No| G[Keep deprecated field]
G --> F
F -->|Yes| H[Remove old field in major version]
B -->|Yes| I[Major version required]
I --> J{Parallel versions viable?}
J -->|No| K[API v2 endpoint or schema]
J -->|Yes| L[Support both old and new in same schema]
K --> M[Notify clients to migrate]
L --> M
M --> N[Sunset old API after deadline]
Frequently asked questions
- What makes a GraphQL change breaking?
- A breaking change is anything that stops existing client queries from working: removing a field, removing an enum value, narrowing a field type, or making a previously-nullable field non-nullable. Adding fields or types is safe—clients ignore what they don't use. Adding new enum values is safe too. Safe changes never need versioning; only breaking changes require a migration strategy.
- Why deprecate fields instead of removing them right away?
- Deprecation gives clients a grace period to migrate off the old field before you remove it. You mark the field as @deprecated in the schema, clients see the warning, and they have a deadline (usually 3-6 months) to switch. Removing immediately breaks surprise consumers and burns trust; deprecation signals change and gives teams time to adapt.
- Should I version GraphQL like REST (v1/v2 URLs)?
- Not usually. GraphQL handles versioning inside the schema via deprecation and new fields. One endpoint, one schema, multiple query support. Versioning becomes necessary only if you need to support truly incompatible schemas concurrently—for example, a major data model restructure. Then you'd offer v1 and v2 endpoints with different schemas, but that's rare. Prefer schema evolution inside one version.
- How do I detect and notify clients still using deprecated fields?
- Log deprecation warnings when deprecated fields are queried, or use analytics to count queries hitting deprecated fields. GraphQL servers can emit deprecation directives that tools like Apollo Client highlight at development time. Send email notifications 3-6 months before sunset deadlines to teams whose client queries still reference the old field.