docs: schema change management#2318
Open
sarahxsanders wants to merge 4 commits into
Open
Conversation
|
@sarahxsanders is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
sarahxsanders
marked this pull request as ready for review
February 17, 2026 22:34
Contributor
Author
|
@martinbonnin needs review |
martinbonnin
approved these changes
Jul 17, 2026
|
|
||
| ## Identify breaking changes | ||
|
|
||
| Breaking changes modify or remove existing schema elements in ways that cause previously valid queries to fail or return different data. |
Contributor
There was a problem hiding this comment.
Suggested change
| Breaking changes modify or remove existing schema elements in ways that cause previously valid queries to fail or return different data. | |
| A breaking change is any change that breaks the server/client contract. This happens when previously valid operations become invalid or when the shape of the returned data changes. | |
| - Changing field types, such as `String` to `Int` | ||
| - Removing or renaming enum values | ||
| - Making optional arguments required | ||
| - Changing argument types |
Contributor
There was a problem hiding this comment.
Suggested change
| - Changing argument types | |
| - Changing argument types | |
| - Making a non-null field nullable |
| } | ||
| ``` | ||
|
|
||
| **Making a nullable field non-null:** |
Contributor
There was a problem hiding this comment.
Suggested change
| **Making a nullable field non-null:** | |
| **Making a non-null field nullable:** |
| } | ||
| ``` | ||
|
|
||
| These examples show schema changes that break existing queries. Clients requesting the removed `email` field receive errors. Clients expecting a `Float` for `price` get a `Money` object instead. Queries relying on `null` discounts fail validation. |
Contributor
There was a problem hiding this comment.
Suggested change
| These examples show schema changes that break existing queries. Clients requesting the removed `email` field receive errors. Clients expecting a `Float` for `price` get a `Money` object instead. Queries relying on `null` discounts fail validation. | |
| These examples show schema changes that break existing queries. Clients requesting the removed `email` field receive validation errors. Clients expecting a `Float` for `price` get a `Money` object instead. Queries relying on `non-null` discounts may crash. |
|
|
||
| ## Handle dangerous changes | ||
|
|
||
| Some changes appear safe but can cause subtle issues. These "dangerous" changes don't break the schema structurally but might break client logic. |
Contributor
There was a problem hiding this comment.
Suggested change
| Some changes appear safe but can cause subtle issues. These "dangerous" changes don't break the schema structurally but might break client logic. | |
| Some changes appear safe but can cause subtle issues. These "dangerous" changes don't break the schema structurally and [robust applications](./robust-applications) can handle most of them but caution must be exercised. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
adds a new guide on schema change management covering schema evolution in GraphQL: