GraphQL / Intermediate: policy, sources and clients / Lesson 11
Schema evolution, deprecation and compatibility
Evaluate changes against deployed operations and business semantics instead of assuming every additive change is safe.
On this page
Lesson goals
- Distinguish structurally breaking changes from behavioral risks.
- Plan deprecation with ownership, usage evidence and migration verification.
Review the schema as a public dependency
Clients can deploy on different schedules from the server, especially mobile applications and third-party integrations. A field rename is therefore a removal plus an addition, not a harmless code cleanup. Changes to argument requirements, scalar representation, authorization, ordering or nullability can affect existing operations even when a schema diff looks small. Keep the domain meaning stable as well as the SDL shape. A field called publishedAt must not silently change from publication time to latest edit time merely because both values serialize as timestamps.
Introduce a replacement before removing a field
Deprecation communicates that clients should migrate; it does not remove the old field or ensure that consumers have stopped using it. The replacement must be implemented and documented with equivalent or intentionally changed semantics. The example keeps name available while introducing title. A useful reason tells clients what to use, while the migration plan belongs in release documentation and ownership records. Avoid dates invented without a support policy. Removal should follow measured usage and the project’s compatibility commitment rather than a developer’s assumption that nobody still uses the field.
type Course {
id: ID!
name: String! @deprecated(reason: "Use title for the course display title")
title: String!
}Both fields remain selectable during migration. A schema can validate old documents until the deprecated field is actually removed.
Input and output compatibility have directions
Making an optional input required can invalidate documents or variable fixtures that omit it. Relaxing an output from non-null to nullable can break clients that safely assumed a value, even though the server gains flexibility. Adding an enum value or union member may surprise generated exhaustive clients. There are specification-level validity rules and ecosystem-level behavior risks, so a structural checker is useful evidence rather than a complete release decision. Test the actual supported client documents, variable cases and generated-code assumptions alongside the schema diff.
Track migration evidence without private values
A migration manifest can name the old coordinate, replacement, owning team and required verification. The JSON below is a local review record, not a schema registry integration or a claim that usage was measured. Real operation telemetry should record safe document identifiers and field usage under an approved retention policy. A zero count in a short observation window does not prove that an infrequent batch client has migrated. Include supported offline and seasonal consumers before deciding the old contract can be retired.
{
"coordinate": "Course.name",
"replacement": "Course.title",
"owner": "training-catalog",
"checks": ["supported-documents-validate", "client-migrations-confirmed", "usage-window-reviewed"],
"removalDecision": "requires-recorded-evidence"
}The manifest records required evidence, not completed checks. It contains no real usage counts or customer document text.
Keep rollback compatibility in the plan
A safe rollout often adds server support, migrates clients, observes usage and only then retires old behavior. Consider rollback: a newly deployed client may depend on a field absent from the previous server release. Keep an overlap window or an explicit capability strategy so restoring the server does not strand the client. Generated types should come from the intended schema artifact and complete operation documents. Pin schema and operation artifacts in review so a build does not silently consume a different remote contract during deployment.
Common errors and fixes
A renamed field breaks old clients
- Why it happens
- Removal was treated as an internal refactor.
- How to fix it
- Restore overlap and migrate supported documents deliberately.
- Prevent it next time
- Run compatibility checks against retained client operations.
A new enum value crashes an exhaustive switch
- Why it happens
- Additive schema change was assumed harmless for generated clients.
- How to fix it
- Add a deliberate unknown-value strategy and update consumers.
- Prevent it next time
- Review enum and union growth in client contracts.
Rollback leaves clients requesting an absent field
- Why it happens
- Server and client release order lacked an overlap plan.
- How to fix it
- Preserve compatible server support across the rollback window.
- Prevent it next time
- Include rollback artifact validation in release review.
Check your understanding
1. Is adding a required argument to an existing field compatible?
Show worked solution
Existing documents that call the field without that argument can become invalid, so the change is breaking for those consumers. Consider a new optional argument with safe documented behavior, or a distinct field when semantics materially differ. Validate retained documents and real variable fixtures rather than assuming that regeneration of one web client represents every supported consumer.
2. What evidence is needed before deleting a deprecated field?
Show worked solution
Identify supported consumers, confirm their migrations, review a representative usage window and validate their current documents against the proposed schema. Include infrequent clients and rollback requirements. Deprecation metadata is notice, not proof of migration, and a brief zero-usage graph cannot establish that every contractual consumer has stopped using the field.
Key takeaways
- Compatibility includes semantics and client assumptions, not only SDL validity.
- Deprecation needs evidence and an overlapping release plan.