Schema proposals
Propose, review, and track changes to new and published schemas
This feature is only available with a
You can test it out by signing up for a free
As your supergraph schema grows, managing changes becomes more difficult.
Assessing the impact of subgraph schema changes on
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—includingschema 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 editoras new fields and types, regardless of formatting.
- In contrast, GraphQL-naive text diffing may not understand and diff changes unless they're conventionally formatted.
- For example, GraphOS diffs additions of new fields and types in the
- Centralizing the schema change process consolidates a comprehensive audit trail of discussions and schema changes.
How schema proposals work
Team members
ⓘ NOTE
Schema proposals—even
Before diving into schema proposal workflow, it's helpful to understand proposal statuses.
Proposal statuses
| Status | Automatic or manually set | Description |
|---|---|---|
| Automatic at proposal creation but can be manually reset | Default status upon creation until the proposal is ready for review. |
| Manual | Signals the proposal is ready for review. - If default reviewers are configured, they become assigned for review. |
| Automatic | 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 . |
| Automatic | Signals all the proposal's changes have been published . - Implemented proposals can't receive further revisions. - Their status can't be updated. |
| 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
To learn more about each stage in the process, refer to the following articles:
- Propose changes
- Review proposals
- Implement proposals(covers both implementation and publication)