Schema Structure

Structural changes to a GraphQL schema come in two categories:

• Breaking changes may cause previously-valid queries to become invalid. For example, if you remove the title field, anyone who tries to query that field will get a validation error instead of response data.
• Non-breaking changes add options to a schema without breaking previously-valid queries.

Making a breaking change can be bad news for your API clients, since their applications may break. But, sometimes they’re required. Non-breaking changes don’t affect existing queries, since they just add new parts to the schema.

Here are few tips for managing schema structure changes.

Maintain a .graphql schema dump

Make structure changes part of the normal code review process by adding a schema.graphql artifact to your project. This way, any changes to schema structure will show up clearly in a pull request as a diff to that file.

You can read about this approach in “Tracking Schema Changes with GraphQL-Ruby” or the built-in GraphQL::RakeTask for generating schema dumps.

Automatically check for breaking changes

You can use GraphQL::SchemaComparator to check for breaking changes during development or CI.