Schema Proposals are a new addition to the Grafbase platform. They will be a core component of our GraphQL schema evolution and management story going forward, with other features interacting and integrating with Schema Proposals. The first iteration of this feature introduces a new addition to the Grafbase Dashboard where proposals can be created, authored, discussed, and reviewed. Schema checks have been extended to optionally enforce that all changes to be published have previously been approved.
Typically, GraphQL Federation is adopted by companies facing the challenges of an increasingly complex and distributed API schema, where different teams own portions of the common API and cannot keep an overview of the whole landscape without help. Federation ensures ownership, avoids conflicts through composition, and solves problems of communication between subgraphs with directives like @requires. It helps make schema evolution safer through schema checks, ensuring, for example, that changes are not breaking thanks to operation checks.
However, these rules and affordances do not help humans agree on schema changes. Schema Proposals fill the gap of a design time tool that integrates the GraphQL schema intelligence built into the platform with a human process of proposing, discussing, and reviewing changes. They are intended to be a principled, functioning process that can be adopted by teams that would have resorted to a homegrown solution.
As a design tool, they improve on home grown solutions through integration with the platform:
- The UI is aware of the current state of the schema. The automatically rebased diff view is a reliable overview of what changes are actually proposed.
- Integrated schema checks can say in advance if the proposed changes pass validation, lint and composition checks, and even if they would be breaking clients with operation checks.
- All proposals have a full edit and review history, with all discussions in one place.
As a governance tool, they enforce approval of schema changes by the relevant reviewers. Schema Proposals only transition to the "approved" state once all configured reviewers (they can be individuals or teams) have given their approval. Schema checks automatically take care of rejecting updates to the schema that have not been approved.
Notifications ensure all configured reviewers and any extra requested reviewers do not miss proposals.
The workflow is optimized for:
- Speed. Proposals do not block each other. Proposals can be implemented incrementally (one subgraph publish can implement part of one or multiple proposals). Proposals are a design time feature; they do not constrain the order of implementation.
- Clear responsibilities. Required reviewers can be configured. They can be teams or individuals. Additional criteria like subgraph ownership can be taken into account for reviewer configuration. Authors of proposals can request reviews from specific individuals and teams in addition to the configured reviewers.
- Visibility. Each revision of the proposal is documented with a message. The activity feed documents all events in the proposal's history. The diff view summarizes the changes.
Anybody can propose changes to any subgraph and submit them for review. The author and the reviewers then have the opportunity to comment on the proposal and iterate. Eventually, the required reviewers either approve or reject the proposal.
When features are implemented and a new version of a subgraph's schema is ready to be published, schema checks take the additional responsibility of enforcing that all changes in the new schema have been approved in a proposal.
The video below shows the workflow in action:
The feature and workflow were designed in collaboration with customers managing large mission-critical APIs with many users. They would have needed an in-house solution to centralize, document, and enforce the approval of schema changes — Schema Proposals are an integrated, out-of-the-box solution for these scenarios.
We are already using Schema Proposals for our own GraphQL API and we will continue making them more feature-rich, integrated, and flexible, but feedback is critical. If you are curious about how schema proposals could fit in your organization, we are always interested in hearing your use cases and your problems. Contact us and get involved in our community.