|
| 1 | +--- |
| 2 | +title: Schema Proposals Preview |
| 3 | +description: A progress update on a much awaited feature -- Schema Proposals! |
| 4 | +date: 2025-09-03 |
| 5 | +authors: [jdolle] |
| 6 | +--- |
| 7 | + |
| 8 | +## What are Schema Proposals? |
| 9 | + |
| 10 | +Schema proposals are an API governance process that shift schema design left, to earlier in your |
| 11 | +development flow. They allow team members to suggest changes to the schema before any code changes. |
| 12 | + |
| 13 | +The way this works is by storing a list of approved changes, and then verifying any new changes |
| 14 | +against this list as part of the usual schema check flow. This way, only approved changes can be |
| 15 | +implemented. |
| 16 | + |
| 17 | +There's lots more to it than that. But luckily you shouldn't have to worry all those details. Let's |
| 18 | +look at what's planned for Schema Proposals in Hive. |
| 19 | + |
| 20 | +### Schema Proposal Lifecycle |
| 21 | + |
| 22 | +```mermaid |
| 23 | +flowchart LR |
| 24 | + Draft --> Open |
| 25 | + Open -.-> Draft |
| 26 | + Open --> Approved |
| 27 | + Approved -.-> Open |
| 28 | + Approved -.->|Wait on changes implementation|Implemented |
| 29 | + Approved -.-> Closed |
| 30 | + Approved -.-> Draft |
| 31 | + Closed <-.-> Draft |
| 32 | + Closed <-.-> Open |
| 33 | +``` |
| 34 | + |
| 35 | +Schema proposals are manually transitioned from Draft to Open to Approved and potentially back or to |
| 36 | +Closed. However, once a proposal is Approved, the set of changes must be matched against published |
| 37 | +schemas before finally being transitioned to Implemented once all changes are accounted for. An |
| 38 | +important detail is that a proposal doesn't need implemented all at once. A subset of changes can be |
| 39 | +completed at a rate that is comfortable to your team. |
| 40 | + |
| 41 | +## Feature Details |
| 42 | + |
| 43 | +### Detailed list of Changes |
| 44 | + |
| 45 | +Much like the existing list of changes inside schema checks, this view gives a concise list of |
| 46 | +changes and includes some metadata for each change, such as whether or not the change is breaking, |
| 47 | +and for Schema Proposals, whether not a change conflicts with the latest schema. For example, if a |
| 48 | +proposal adds field to an existing type, but that type gets removed before the proposal can be |
| 49 | +implemented. |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +### Minimal Schema Diff |
| 54 | + |
| 55 | +Showing a diff of the schema definition language (SDL) gives a clear picture of what your schema |
| 56 | +will look like. For this view, we opted to not using existing string diffing options that are |
| 57 | +typically used. This helps keep te rendered diff concise since we can control formatting and |
| 58 | +ordering to avoid unnecessary noise for example, when changing the order of definitions in your SDL. |
| 59 | + |
| 60 | +If using GraphQL Federation, then each subgraph will be rendered separately on this view: |
| 61 | + |
| 62 | + |
| 63 | + |
| 64 | +A separate view is available to see the diff for the entire supergraph. This is helpful for |
| 65 | +confirming how subgraphs combine. |
| 66 | + |
| 67 | +### Schema Checks |
| 68 | + |
| 69 | +Schema Proposals are implemented on top of an existing feature -- Schema Checks. Every proposed |
| 70 | +change to a graph will trigger a schema check and those are all tracked in this view. This is also a |
| 71 | +history of all the proposed versions of a proposal. |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | +### Reviews and Comments |
| 76 | + |
| 77 | +A critical part of proposals is giving team members an opportunity to comment on the changes. This |
| 78 | +collaboration is key to producing high quality APIs. We plan to fully support adding comments to |
| 79 | +parts of the schema for detail and to the proposal on a whole for general statements about the |
| 80 | +entire effort. |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +Schema proposals are scheduled to be released later this year. |
| 85 | + |
| 86 | +We hope you enjoyed this preview of our work. If you have any feedback or additional requests, then |
| 87 | +please don't hesitate to contact us via Slack or chat with us through our website. |
0 commit comments