Schema Proposal Configurations
Configure default reviewers, approval requirements, and more
Org and graph admins can configure these aspects of schema proposals:
| Configuration | Description |
|---|---|
| Permissions | Which roles can create and edit proposals |
| Default reviewers | Which team members are default reviewers and whether default reviewer approval is required |
| Required approvals | The minimum number of approvals needed for a proposal to achieve Approved status |
| Require reapprovals after revisions | Whether to require reapprovals after an approved proposal is revised |
| Description template | An editable description that prepopulates every new proposal created for the graph |
| Schema checks | Whether and how schema checks incorporate proposals |
| Notifications | Whether to send email notifications for proposal activity |
Configurations are available on a graph's Settings page in GraphOS Studio.
Configure permissions and approvals
Permissions for proposal actions are set at the graph level with the following defaults:
| Proposal Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| Change proposal status | ✓ | ✓ | |||
| Create proposals | ✓ | ✓ | ✓ | ✓ | |
| Edit proposals | ✓ | ✓ | ✓ | ✓ | |
| Add reviewers | ✓ | ✓ | ✓ | ✓ | |
| View proposals | ✓ | ✓ | ✓ | ✓ | ✓ |
| Make comments | ✓ | ✓ | ✓ | ✓ | ✓ |
| Approve proposals | ✓ | ✓ | ✓ | ✓ | ✓ |
Org and graph admins can configure which roles can create and edit proposals. Permissions for other proposal actions aren't configurable. Refer to the configuration reference table below for default and valid values.
Configuration reference
| Configuration/ Default value |
Description/ Valid values |
|---|---|
PermissionsDefaults:
| The minimum role required to create or edit proposals.Observers is the least restrictive setting and Admins the most restrictive.The Observers default for creating proposals means all organization members except Consumers and Billing Managers can create proposals.The Admins default for editing proposals means only org and graph admins can edit proposals they didn't create.Proposal authors can always edit their own proposals regardless of their role.Valid values:Admins, Contributors, Documentors, or Observers |
Default reviewersDefault:None | The team members automatically marked as reviewers once a proposal's status becomes Open for feedback.Valid values:Any member of your organization can be a default reviewer except for billing managers. |
Required approvalsDefault:3 | The minimum number of approvals a proposal must receive for its status to become Approved.Valid values:1 - 6 |
Require default reviewer approval
By default, any team member's approval can contribute to the minimum number of required approvals. Once you've added default reviewers, you can require at least one approval to come from a default reviewer by selecting Require at least one default reviewer for all proposals on this graph.
Require reapprovals
By default, if a proposal is revised after one or more approvals, the approved status stays. You can change this to withdraw approvals from revised proposals.
In your proposal settings, click Manage approval requirement, and select Withdraw previous approvals on new revisions. With this setting enabled, reviews are rerequested automatically from anyone who previously approved.
Configure description template
When you create a proposal, you can optionally include a description that appears on the proposal's Overview tab. Proposal descriptions support Markdown.
Setting a graph's Description template prepopulates the description for every new proposal any team member creates for the graph. Templates can help ensure that all proposal descriptions follow a particular format.
You can edit a prepopulated description during proposal creation and throughout the proposal process.
Configure schema checks
You can configure schema checks to include a Proposals task that verifies whether the changes a check is running on have matching and approved schema proposals.
By default, the severity of this task is Off. You can select from the following severity levels:
(Default) With the severity set to Off, the proposals task isn't part of the checks that changes must pass for the schema check to succeed.
Setting the severity to Error means the proposals task fails when the change being checked isn't included in approved proposals.
Setting the severity to Warning means the proposals tasks can still pass even when the change being checked isn't included in approved proposals. However, warnings appear in the check run.
Integrating the Proposals task into schema checks strengthens schema governance when publishing changes. See the proposals implementation article for more information on how to use schema checks as part of your proposal workflow.
Notifications
By default, all team members receive email notifications for the following:
If you're selected as a reviewer on a proposal, whether because you are a default reviewer, or you've been manually selected
Whenever you are
@mentioned in a comment
Additionally, the following roles receive email notifications for the following proposal actions:
| Comments | Saved Revisions | Status Changes | Reviews | |
|---|---|---|---|---|
| Proposal author | ✔️ | ✔️ | ✔️ | ✔️ |
| Commenter | ✔️ ** | ❌ | ❌ | ❌ |
| Reviewer | ❌ | ✔️ | ❌ | ❌ |
| Proposal editor | ❌ | ❌ | ❌ | ❌ |
Notifications are cumulative. For example, if you comment on a particular thread and review a proposal, you get notifications for both new comments on the thread and saved revisions.
Turn off notifications
Notifications are enabled by default. To turn off your notifications, go to the schema proposal's overview page and click the bell icon.
To re-enable them, click the same bell icon.