---
title: "Check every schema change for breaking · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/graphql-and-grpc/schema-breaking-checks
id: API-88
level: Recommended
updated: 2026-10-22
tokens: 763
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Check every schema change for breaking changes in CI

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-88
- Level: Recommended
- Chapter: [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)
- Rule: Compare each change to a GraphQL schema or protobuf file with the version on the main branch in CI. Fail the build on a breaking change unless the pull request carries an approved label.
- Check: Open a test pull request that removes one field from the schema. CI fails and names the field. With the approved label, the same change passes.
- How: A removed field or a changed type is easy to miss in review and breaks clients you cannot see. Tools such as `buf breaking` for protobuf and GraphQL Inspector for GraphQL read both versions and list each break. Keep the schema file in the repository as the contract, as [write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract.md) says for OpenAPI. Generate clients from it as [generate docs and clients from the contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/generated-docs.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```bash
buf breaking --against '.git#branch=main'
npx graphql-inspector diff 'git:origin/main:schema.graphql' schema.graphql
```

## Sources

- [GraphQL schema design on versioning](https://graphql.org/learn/schema-design/)
- [Protocol Buffers proto3 guide on updating a message type](https://protobuf.dev/programming-guides/proto3/)

## Related rules

- API-45 [Write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract.md) in API design
- API-48 [Generate docs and clients from the contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/generated-docs.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc/schema-breaking-checks">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Never reuse or change a protobuf field number](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/protobuf-field-numbers.md)
- Next: [Set a deadline on every gRPC call and pass it on](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/grpc-deadlines.md)
- [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)