Skip to content

Commit bdfc51d

Browse files
authored
docs: add proposal preview to product updates (#6939)
1 parent 1087e74 commit bdfc51d

File tree

5 files changed

+87
-0
lines changed

5 files changed

+87
-0
lines changed
168 KB
Loading
386 KB
Loading
196 KB
Loading
83.6 KB
Loading
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
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+
![Schema Proposal details tab](/changelog/2025-09-03-schema-proposals/details.png)
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+
![Schema Proposal schema tab](/changelog/2025-09-03-schema-proposals/schema-diff.png)
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+
![Schema Proposal checks tab](/changelog/2025-09-03-schema-proposals/checks.png)
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

Comments
 (0)