⬡ GraphQL Advanced

How do you implement schema evolution and versioning in GraphQL?

Answer

GraphQL's approach to evolution avoids explicit versioning through continuous schema evolution: (1) Add, don't remove: always add new fields/types; never remove them immediately. Old clients continue working. (2) Deprecation: mark old fields with @deprecated(reason: "Use newField instead") — tools warn developers; field still works. (3) Usage analytics: use Apollo Studio's field usage tracking to identify when deprecated fields have zero usage before removing them. (4) Backward-compatible changes: safe — adding optional arguments (with defaults), adding nullable fields, adding types, adding enum values (carefully — clients should handle unknown values). (5) Breaking changes: unsafe — removing fields, changing non-null to null (ok) or null to non-null (breaking), changing argument types, renaming. (6) Schema checks: use rover graph check or Apollo Studio to automatically detect breaking changes in CI. (7) Field aliasing: add new field returning differently shaped data; alias old field to new implementation during transition.