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.
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.
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.
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.
Before diving into schema proposal workflow, it's helpful to understand proposal statuses.
|Automatic at proposal creation but can be
|Default status upon creation until the proposal is ready for review.
|Signals the proposal is ready for review.
- If default reviewers are configured, they become assigned for review.
|Signals the minimum number of reviewers has approved the proposal.
- If you've required default reviewer approval, at least one approval must be from a default reviewer.
|Signals all the proposal's changes have been published.
- Implemented proposals can't receive further revisions.
- Their status can't be updated.
|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.
Schema proposal statuses enable the following end-to-end schema change management workflow:
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, and more.
To learn more about each stage in the process, refer to the following articles: