Schema Proposals
Propose, review, and track changes to new and published schemas
As your supergraph schema grows, managing changes becomes more difficult. Assessing the impact of subgraph schema changes on composition and client operations becomes more complex. Once schema design changes are agreed upon, implementing them during subgraph development poses another challenge.
These challenges grow when updating multiple subgraph schemas simultaneously and collaborating across teams. Schema development can stall without the clear cross-team communication needed to understand, verify, and track changes.
Schema proposals for schema change management
GraphOS schema proposals provide centralized schema change management. The centralized proposal process fosters collaboration and strengthens schema governance:
Subgraph developers can propose changes in the context of the supergraph using automated checks and reviewer feedback for validation.
Graph consumers can actively participate by commenting on, reviewing, and approving proposals.
Graph owners and governance teams can use proposals to set standards and ensure only approved changes are published.
This increased coordination improves design decisions and accountability, streamlining development cycles.
Benefits of native schema change management
Managing schema changes directly in GraphOS Studio provides the following benefits:
The proposal process uses GraphOS schema checks—including schema linting—at every step.
This minimizes the likelihood of errors and inconsistencies.
It also offers an immediate understanding of the changes' impacts on composition and client operations.
Editing, reviewing, and approving changes in GraphOS allows for GraphQL-aware schema diffing.
For example, GraphOS diffs additions of new fields and types in the proposals editor as new fields and types, regardless of formatting.
In contrast, GraphQL-naive text diffing may not understand and diff changes unless they're conventionally formatted.
Centralizing the schema change process consolidates a comprehensive audit trail of discussions and schema changes.
How schema proposals work
Team members create, review, and approval schema proposals in GraphOS Studio. After approval, the team implements the proposal—including resolvers and any supporting code changes— before publishing the schema changes to GraphOS.
Org and graph admins can configure schema checks to ensure an organization only publishes changes approved through a proposal.
Before diving into schema proposal workflow, it's helpful to understand proposal statuses.
Proposal statuses
| Status | Automatic or manually set |
Description |
|---|---|---|
Draft | Automatic at proposal creation but can be manually reset | Default status upon creation until the proposal is ready for review. |
Open for feedback | Manual | Signals the proposal is ready for review.
|
Approved | Automatic | Signals the minimum number of reviewers has approved the proposal.
|
Implemented | Automatic | Signals all the proposal's changes have been
published. - Implemented proposals can't receive further revisions. - Their status can't be updated. |
Closed | Manual | Signals the proposal is suspended or abandoned. - Closed proposals can't receive further revisions. - You can reopen a proposal by setting the status to Draft or Open for feedback. |
A proposal doesn't have to progress linearly from Draft to Implemented. For example, it may be Closed before returning to Draft and continuing through the process.
Proposal workflow
Schema proposal statuses enable the following end-to-end schema change management workflow:
Legend
Next steps
Schema proposal default configurations let you start using proposals out of the box. If you want to fine-tune your graph's proposal process, check out Configure proposals. Configurations include permissions, approval requirements, email notifications, and more.
To learn more about each stage in the process, refer to the following articles:
Implement proposals (covers both implementation and publication)