Schema Evolution, Deprecation and Registries — GraphQL in Production

GraphQL APIs usually evolve without versioning: add fields and types freely, mark old fields @deprecated(reason: "Use totalPrice"), monitor usage, and remove only when no client uses them. A schema registry checks every proposed schema against recent real traffic in CI and blocks breaking changes (removing fields, making nullable fields non-null in inputs, changing types). Communicate deprecations in changelogs and client SDK warnings.

Compatibility of schema changes

Change	Safe?	Notes
Add field / type / enum value (output)	Usually	Clients must tolerate unknown enum values
Add optional argument / input field	Yes
Add required argument / input field	No	Breaks existing operations
Remove or rename field	No	Deprecate first, check usage
Nullable → non-null (output)	Yes	Stronger guarantee
Non-null → nullable (output)	Risky	Clients may not handle null

type Order {
  total: Money!
  price: Float @deprecated(reason: "Use total (Money) instead; removal after 2027-03-01")
}

# CI: compare schema against production traffic (e.g. `rover subgraph check`, `hive schema:check`)

Common pitfalls

Removing fields based on guesses instead of usage data.
Adding enum values that crash clients with exhaustive switches.
Creating /v2 GraphQL endpoints instead of evolving.

Key points

Additive evolution, no versions
@deprecated + usage monitoring
Registry checks in CI

Further reading: GraphQL best practices: Versioning

Practice questions

Why is adding a required argument a breaking change?

Answer

Existing operations that don't pass it will fail validation; new arguments must be optional (with defaults).

How do you decide when a deprecated field can be removed?

Answer

Monitor field usage per client in a schema registry/analytics, notify remaining consumers, and remove after usage reaches zero (or after an announced deadline).