Operation checks have been a cornerstone of safe schema evolution in Grafbase, preventing breaking changes by analyzing actual API usage patterns. But what happens when usage data isn't available? Multi-tenant environments, new APIs, and certain architectural patterns can make it difficult or impossible to rely on usage analytics for breaking change detection. Depending on your setup, you may also just want that process to have a human review component.
Today, we're introducing Breaking Change Approvals — a powerful combination of Schema Proposals and Operation Checks that enables safe schema evolution even without usage data.
Breaking Change Approvals introduces two new settings in your operation checks configuration:
Ignore usage data for operation checks: When enabled, operation checks will flag all theoretically breaking changes, regardless of actual usage. This ensures nothing slips through the cracks in environments where usage tracking isn't comprehensive.
Allow breaking changes from approved proposals: This setting creates a powerful workflow where breaking changes must first be proposed, reviewed, and approved through Schema Proposals before they can be deployed.
The combination creates a human-in-the-loop approval process that maintains the safety guarantees of operation checks while adapting to scenarios where automated usage analysis isn't sufficient.
You can use the second setting without the first, which would have the effect of operation checks ignoring breaking changes that have either been approved or only touch unused parts of the schema.
With Breaking Change Approvals enabled, your schema evolution process becomes:
- Propose — Create a schema proposal documenting the breaking changes you need to make
- Review — Collaborate with your team, discuss the implications, and gather approvals
- Publish — Once approved, the breaking changes are automatically allowed through operation checks
This workflow ensures that breaking changes are intentional, documented, and reviewed by the appropriate stakeholders before they can affect your production API.
Potentially breaking changes can be dangerous, and some teams want them to be scrutinized by specific reviewers (you can assign default reviewers, users or teams, for schema proposals), without adopting schema proposals for additive changes.
In multi-tenant platforms, you may just not have access to usage data, so breaking change approvals would be the only way to distinguish between breaking changes that are OK and those that are actually breaking.
Breaking Change Approvals is available now for all Grafbase Cloud and Enterprise Platform users. To enable it:
- Navigate to your Graph Settings
- Find the Operation Checks section
- Enable both "Ignore usage data" and "Allow approved breaking changes" options
- Start creating proposals for your breaking changes
For detailed configuration instructions and best practices, check out our documentation.
This feature was developed in collaboration with customers managing complex, multi-tenant GraphQL APIs. We're excited to see how it helps you manage schema evolution in your organization. Join us on Discord to share your experience and help shape the future of schema management in Grafbase.