2
2
This document formally defines the process used to evolve the JSON Schema
3
3
specification as of the first stable release in 2023. It applies to the core
4
4
specification and the specifications for any dialects and vocabularies
5
- maintained by the JSON Schema Org. It does not necessarily apply to everything
6
- the JSON Schema Org maintains. For example, media type registration follows the
7
- IETF process. Certain components used within JSON Schema, such as Relative JSON
8
- Pointer, may also follow a separate process.
5
+ maintained by the JSON Schema Org, but it doesn't necessarily apply to
6
+ everything the JSON Schema Org maintains. For example, media type registration
7
+ follows the IETF process. Certain components used within JSON Schema, such as
8
+ Relative JSON Pointer, may also follow a separate process.
9
+
10
+ This process doesn't apply to third-party dialects, vocabularies, or other
11
+ extensions. However, third-parties are welcome to use this as a basis for the
12
+ process they use for their specifications.
9
13
10
14
## Canonical URLs
11
15
There MUST be a stable canonical URL for referencing any specification that
@@ -24,10 +28,14 @@ merged in the last quarter.
24
28
25
29
## The Stability Model
26
30
Every feature in the spec has a release status. It's either evolving, stable, or
27
- deprecated. Flags are used to show the status a feature is in. If a feature
28
- doesn't have a flag, it's considered stable. If it has a year flag (such as
29
- ` 2024 ` ) that's the year the feature reached stability. The other flags indicate
30
- a feature that is not yet stable or is deprecated.
31
+ deprecated. Flags are used to show the status a feature is in. If it has a year
32
+ flag (such as ` 2024 ` ) that's the year the feature reached stability. The other
33
+ flags indicate a feature that is not yet stable or is deprecated.
34
+
35
+ If a feature doesn't have a flag, it's considered stable. A feature can only be
36
+ unflagged if it was stable in the initial stable release in 2023. Any functional
37
+ change to the spec after the initial stable release MUST have a flag indicating
38
+ it's status.
31
39
32
40
### Champions
33
41
Any feature that is evolving SHOULD have a champion. The champion is responsible
@@ -45,11 +53,11 @@ Features that could be problematic for forward compatibility are highly
45
53
discouraged, but may be considered if the feature is optional and disabled by
46
54
default.
47
55
48
- ** Promotion Checklist:**
56
+ ** Promotion to STAGE-0 Checklist:**
49
57
[ ] Consensus among JSON Schema Org core contributors that the proposal is worth
50
58
pursuing
51
59
[ ] The proposal has a champion
52
- [ ] A PR for an entry for in the ` STAGE-0 ` registry has been approved
60
+ [ ] A PR for an entry in the ` STAGE-0 ` registry has been approved
53
61
54
62
### STAGE-0
55
63
` STAGE-0 ` features are tracked in the ` STAGE-0 ` Registry on the website. This
@@ -63,7 +71,7 @@ issues that might lead to low adoption such as difficulty of implementation or
63
71
performance implications. Therefore, these implementations don't need to be
64
72
publicly available or have real world use at this point.
65
73
66
- ** Promotion Checklist:**
74
+ ** Promotion to STAGE-1 Checklist:**
67
75
[ ] There is general consensus among the core contributors for adding the feature
68
76
to the spec
69
77
[ ] Tests are available in the test suite
@@ -73,14 +81,14 @@ publicly available or have real world use at this point.
73
81
removes the feature from the ` STAGE-0 ` registry.
74
82
75
83
### STAGE-1
76
- ` STAGE-1 ` features are included to the specification, but flagged as ` STAGE-1 `
84
+ ` STAGE-1 ` features are included in the specification, but flagged as ` STAGE-1 `
77
85
and are not subject to the compatibility requirements of "stable" features. They
78
86
can be added at any time as long as it meets all criteria for ` STAGE-1 ` status.
79
87
80
88
At this stage, the feature should be seeing real world use. These features MAY
81
89
change or be removed all together based on what we learn from real world usage,
82
90
but anything more than small changes should be extremely rare. Any necessary
83
- feature experimentation and evolution should have be done in ` STAGE-0 ` .
91
+ feature experimentation and evolution should have been done in ` STAGE-0 ` .
84
92
85
93
Implementers are encouraged to implement ` STAGE-1 ` features, but are not
86
94
expected to maintain support for previous versions if they change. Users who
@@ -91,7 +99,7 @@ A `STAGE-1` feature can be promoted to `STAGE-2` at any time. Ideally a
91
99
feature should stay in ` STAGE-1 ` for about one year, but may stay longer if we
92
100
don't see it used enough in the wild.
93
101
94
- ** Promotion Checklist:**
102
+ ** Promotion to STAGE-2 Checklist:**
95
103
[ ] There is general consensus that the feature has been proven to be a good
96
104
addition to JSON Schema and is unlikely to change.
97
105
[ ] We see the feature being used successfully in the wild and not generating a
@@ -117,7 +125,7 @@ year to allow implementations to catch up.
117
125
118
126
` STAGE-2 ` features can only be promoted to stable as part of a release.
119
127
120
- ** Promotion Checklist:**
128
+ ** Promotion to Stable Checklist:**
121
129
[ ] The vast majority of actively maintained implementations support the feature
122
130
123
131
### Stable
@@ -148,15 +156,15 @@ Implementations that express support for a particular release MUST support all
148
156
features that are stable as of that release.
149
157
150
158
A snapshot of the spec will be taken of the stable parts of the spec and made
151
- available as a PDF on the website at .
159
+ available as a PDF on the website.
152
160
153
161
## Meta-Schemas
154
162
Meta-schemas associated with the specification(s) maintained under this process
155
163
are subject to the same compatibility rules as the specification. They can be
156
164
updated at any time, but changes MUST be backward compatible and allow for
157
165
forward compatibility with future schemas.
158
166
159
- Meta-schema URIs SHOULD not change once published, but if they do, the old URI
167
+ Meta-schema URIs SHOULD NOT change once published, but if they do, the old URI
160
168
MUST remain available and redirect to the new URI.
161
169
162
170
Meta-schemas are considered non-normative. It's sometimes not possible or not
0 commit comments