GraphQL Breaking Changes

Diff two versions of a GraphQL schema and see what changed for the clients of your API.

Changelog · Contributing

A text diff of a schema tells you which lines moved. It doesn't tell you that Book.isbn losing its ! means every client that trusted it now has to handle null, that the enum value you added will trip exhaustive switches in generated code, or that making an argument required rejects every query written before today. This extension reads both versions of the schema and lists the changes as a client sees them:

• Breaking: queries or clients that work today will fail. A removed type, field, enum value or union member; a field that can now be null; a new required argument or input field; a removed directive location.
• Dangerous: depends on the client. A new enum value or union member (exhaustive switches and fragments stop being exhaustive); a default value added or changed (the server does something new for clients that omit it); a deprecated field removed.
• Other: everything else clients can see: new types and fields, deprecations, descriptions, directives applied.

Direction matters: a field becoming non-null is safe for the client that reads it, while an argument becoming non-null is breaking for the client that sends it. Every change is judged from the side it affects.

It reads SDL (.graphql, .graphqls, .gql), schemas split across many files with their extend type extensions, and introspection results (schema.json, as codegen and Apollo write them), in any combination: an introspection result against the SDL it came from has no changes. Federation subgraphs compare as they are: @key, @external, extend type of a type defined elsewhere, no directive definitions needed. It runs locally in the editor; nothing is sent anywhere.

Install

From the Visual Studio Marketplace, from Open VSX (VSCodium, Cursor and other editors), or from a terminal:

code --install-extension heyliam.graphql-breaking-changes

Getting started

Open a schema and press Ctrl+K B (Cmd+K B on macOS), then pick the branch or tag to compare with, for example main or the tag of the last release.

Files are recognised as schemas by their content (type definitions, or a __schema introspection result), whatever they are called.

The report

• Counts at the top: breaking, dangerous, other, and ignored. Click one to hide or show that level.
• Grouped by type, with the schema's own changes (root types, description) first and directive definitions last. Within a type, breaking changes come first, then by field; each row names the field, input field, enum value or union member it is about.
• Search by type, field, change id or text: / jumps to the box.
• Click a change, or the old 42 / new 57 buttons, to open the schema at that line. For a split schema the button names the file. For an introspection result it opens the JSON at the type, field or argument.
• Copy as Markdown puts a changelog on the clipboard for a pull request, grouped by type.
• Release Notes opens the same changes as release notes for clients (below).
• Ignore (the eye on each change) adds a rule to the settings: this change, every change of that kind, everything on that field, or everything on that type.

The report follows your edits: change the schema, or any file it is merged with, and it updates.

Release notes

Write Release Notes… (in the Command Palette and the editor's context menu) asks for the last release, offering the latest tag first, and then the new one: the working copy, a tag, branch or commit. It opens Markdown for the people who use the API, ready to edit and paste into a release:

## Schema changes in `v2.0.0`

Changes since `v1.0.0`, in `schema.graphql`. 12 breaking changes, 8 dangerous changes, 12 additions, 7 other changes.

### Breaking changes

- `type Book`
  - Field `Book.isbn` can now be `null`: `String!` → `String`
  - Field `Book.pages` changed type: `Int` → `String`
- `type Query`
  - Argument `first` of `Query.books` became required: `Int` → `Int!`, default `20` removed
  - Field `Query.author` removed
…

### Dangerous changes

- `enum OrderStatus`: Enum value `OrderStatus.REFUNDED` added: fields return `OrderStatus`, so clients with an exhaustive switch may break _(may break some clients)_
…

### Added

- `type Mutation`: Field `Mutation.deleteBook` added
…

Breaking changes come first, then dangerous ones, then what is new, then everything else. Ignored changes are left out. The Release Notes button in a report does the same for the two sides it compares.

Breaking changes in the Problems panel

Set graphqlBreakingChanges.baseRef to the branch or tag your API is released from, and every open schema file is checked against it as you type. Breaking changes show up as problems on the field, argument or value that caused them. A removal shows on what is left of it: a removed field on its type, a removed argument on its field, a removed type at the top of the file it was in:

// .vscode/settings.json
"graphqlBreakingChanges.baseRef": "main"

A change in another file of a split schema is a problem in that file, and editing that file checks the schema again. A file that is only a part of a split schema (no root type, no schema block) is checked as the whole schema of the nearest main file in its folder or a folder above it, so a type moved into another file is not taken for removed. If the ref names no branch, tag or commit in the repository (a typo, or a branch not fetched yet), a message says so. When the check can't run (the schema doesn't parse, Git isn't available, or the schema can't be read at the ref), a note on the first line of the file says why, and when only some files of a huge split schema could be read, a note says that too. So an empty Problems panel means no breaking changes.

The quick fix (Ctrl+.) opens the full report or ignores the change. graphqlBreakingChanges.problemsLevel chooses which levels appear (by default, breaking and dangerous).

Schemas split across files

A schema kept as several files (schema.graphql with types/*.graphql holding extend type Query { … } and more types) is read as one. graphqlBreakingChanges.schemaFiles (default **/*.{graphql,graphqls,gql}) names the other files, as a glob matched relative to the folder of the file you compare, so comparing any file of the split brings in the files next to it and below, except in node_modules, dist, out, build and vendor folders, on disk and at a Git ref alike. Files that hold only queries or fragments are left out, and so is a file that defines a type the file you compare defines too: that is another version of the schema (schema-v2.graphql next to schema.graphql), not a part of it. A file that doesn't parse is left out with a note in the report. When a type is defined twice, the definition in the file you compare wins, then the first by path, and the report says so.

Comparing with a Git ref reads every file at that ref, so a file deleted since then still counts: its types are reported as removed. Set the pattern to "" to compare one file on its own.

Introspection results

A schema.json (the result of the introspection query, with or without the data wrapper) compares like SDL, on either side. Descriptions, deprecations, default values, @specifiedBy and @oneOf are read when the result includes them; applied directives other than those are not part of introspection, so a schema's @key or @auth show as removed when its introspection result is compared with its SDL.

Settings

Every setting can differ per folder, so a multi-root workspace with several APIs can give each its own baseline and rules in the folder's .vscode/settings.json.

Ignore rules

"graphqlBreakingChanges.ignore": [
  "enum-value-added",                                        // a change id, anywhere
  "*-description-changed",                                   // * matches any run of characters
  { "type": "Internal*", "reason": "not public" },           // every change on these types
  { "id": "field-removed", "type": "User", "field": "legacyId" },
  { "type": "@auth" }                                        // a directive definition
]

Ignored changes stay in the report, dimmed and struck through with their reason, and are left out of the counts, the Problems panel, the Markdown changelog and the release notes. field matches a field, input field, enum value or union member; for a change to an argument it matches the argument's field.

In Restricted Mode the workspace's ignore, baseRef and schemaFiles settings are not applied, so a repository you just cloned can't hide its own breaking changes or point the comparison at files of its choosing, and nothing that runs Git starts. Comparing two files still works there; Ignore then offers to put the rule in your user settings.

Commands

All are under GraphQL Breaking Changes in the Command Palette.

How levels are chosen

The question is always: does a client that works today, written against the old schema, still work? Some calls are judgement calls, made on purpose:

• A field that can now be null is breaking, at any depth: [String!] → [String] too. Generated types and hand-written code alike assume the non-null they were given.
• A new enum value is dangerous only where a field returns the enum. An enum that is only ever sent by clients gains nothing they have to handle, so there it is informational.
• A new union member or a new implementor of an interface is dangerous: a query that spread fragments over every member stops covering them all, and gets back objects with only __typename.
• A new optional argument or input field is informational when it has no default: existing queries are unaffected. With a default it is dangerous, because the server now does something for every client that leaves it out. A default added to a value that was required is informational: those clients always sent it.
• An argument or input field that becomes non-null is breaking; when a default is added at the same time, clients that omit it still work and only those sending an explicit null break, so it is dangerous.
• Removing a deprecated field, argument, input field or enum value is dangerous, not breaking: clients were told. Removing one that wasn't deprecated is breaking.
• Applied directives are informational, federation's included (@key, @external, @shareable, …): they describe how the graph is composed, not what a client can query. Clients that depend on a custom directive can watch directive-usage-* through treatWarningsAsErrors and ignore rules.
• Descriptions are informational, and kept: they are the documentation clients read.

Detected changes

Each change has an id, used in ignore rules and shown in the report and the Problems panel. Arguments, input fields and directive arguments share one set of rules, since all three are values the client sends: argument-became-required, input-field-became-required and directive-argument-became-required are the same rule in three places.

Schema

Types

Fields

Arguments

Input objects

Enums

Unions and interfaces

Directives

Directive usage

Known limitations

• Changes are found by comparing the two schemas, not the resolvers behind them: the schema has to be accurate, and a field whose type didn't change but whose meaning did is not a change here.
• A renamed type or field is a removal and an addition. Nothing in a schema says a rename happened.
• Changes to a schema's validity (an object type that stops implementing an interface's field, a union of input types) are not reported as such: the schema is read as written, without validation, so that partial and federated schemas compare too.
• Operation documents (query { … }) and gql tagged templates in code are not read: the comparison is of schemas. Which of your queries a breaking change actually breaks is a question for a validator with your documents.
• Whether a default value's change matters depends on what the server does with it: every changed default is reported as dangerous.
• An introspection result carries no applied directives other than @deprecated, @specifiedBy and @oneOf, and no positions: changes point at the "name" of the type, field, argument or value in the JSON.
• For a split schema the other files are found from the folder of the file being compared and below (never through symbolic links), up to 2,000 files, and only regular files up to 64 MB. Comparing a Git revision of a file in a diff editor (Source Control, Timeline) reads the split schema from Git too; other diff providers give one file.
• Large schemas work: GitHub's public schema (about 1 MB of SDL, 1,400 types) compares with an older version in a fifth to a third of a second; the same pair as introspection JSON (4–5 MB each) in under a second. Comparisons run in a worker thread, so they never hold up the editor; one that takes more than two minutes is stopped. The report and the Problems panel follow your typing for schemas up to 3 MB; larger ones are compared again when saved. The report shows the first 1,500 changes until you ask for all.

Privacy

Everything runs locally. The extension makes no network requests and collects no telemetry. It reads the schemas you compare, the files they are split into, and, to compare with Git, the repository through VS Code's Git extension or the git command.

Requirements

VS Code 1.90 or newer. Comparing with Git, release notes and the Problems panel check need Git and a trusted workspace.

License

MIT. The extension includes graphql (MIT) and Codicons (CC BY 4.0 and MIT); see ThirdPartyNotices.txt.