Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Schema Proposals

Propose, review, and track changes to new and published schemas


This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.

As your grows, managing changes becomes more difficult. Assessing the impact of changes on composition and client becomes more complex. Once schema design changes are agreed upon, implementing them during development poses another challenge.

These challenges grow when updating multiple 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

provide centralized schema change management. The centralized proposal process fosters collaboration and strengthens schema governance:

  • developers can propose changes in the context of the using automated checks and reviewer feedback for validation.
  • 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 provides the following benefits:

  • The proposal process uses GraphOS schema checksincluding schema lintingat every step.
    • This minimizes the likelihood of errors and inconsistencies.
    • It also offers an immediate understanding of the changes' impacts on and client operations.
  • Editing, reviewing, and approving changes in GraphOS allows for -aware schema diffing.
    • For example, GraphOS diffs additions of new 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 proposalincluding and any supporting code changes before publishing the schema changes to GraphOS.

NOTE

—even approved ones—don't deploy any changes to your . Once a proposal is approved, your team must implement and publish the changes.

Org and graph admins can configure schema checks to ensure an organization only publishes changes approved through a proposal.

Before diving into workflow, it's helpful to understand proposal statuses.

Proposal statuses

StatusAutomatic 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
ManualSignals the proposal is ready for review.

- If default reviewers are configured, they become assigned for review.
Approved
AutomaticSignals 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.
Implemented
AutomaticSignals all the proposal's changes have been published.

- Implemented proposals can't receive further revisions.
- Their status can't be updated.
Closed
ManualSignals 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

statuses enable the following end-to-end schema change management workflow:

Proposal creation
Start proposal
Draft status
Edit subgraphs, lint,
save, and check changes
Request reviews

Proposal review
Open for
feedback
status
Receive feedback
Address feedback
Receive
minimum approvals

Proposal implementation
Approved
status
Fetch proposal and
implement locally
Run checks on
local changes
GraphOS
schema checks

Proposal publication
Schema checks
pass
Publish schema
to GraphOS
GraphOS matches
changes to proposals
Implemented
status

Legend

Proposal
status
User action
Automated
GraphOS action

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:

Previous
Linter Rules
Next
Configure Proposals
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company