Skip to content

Commit db8004b

Browse files
committed
tweaks to language; add a stability table
1 parent b6c7a98 commit db8004b

File tree

1 file changed

+35
-6
lines changed

1 file changed

+35
-6
lines changed

PROCESS.md

+35-6
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This document describes the development and publication process for the JSON Sch
1313

1414
Some behaviors within JSON Schema may be explicitly or implicitly undefined by the specifications for various reasons. How to handle these behaviors is generally left to implementations.
1515

16-
A defined behavior is one that is fully defined by the specifications.
16+
A defined behavior is one that is fully and unambiguously defined by the specifications.
1717

1818
### Stability and Breaking Changes
1919

@@ -23,6 +23,35 @@ If an existing schema under the new release exhibits defined behavior that is co
2323

2424
If a new release fully defines a previously undefined (or under-defined) behavior, the new release is still considered compatible, even if it contradicts the decision of any particular implementation.
2525

26+
For reference, this table shows the validation results of a hypothetical schema and instance across two consecutive releases to illustrate the compatibility of those releases:
27+
28+
<table>
29+
<tr>
30+
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Next➡️<br>⬇️Current</td>
31+
<th width="100" align="center">true</th>
32+
<th width="100" align="center">false</th>
33+
<th width="100" align="center">indeterminant</th>
34+
</tr>
35+
<tr>
36+
<th align="center">true</th>
37+
<td align="center">✅</td>
38+
<td align="center">❌</td>
39+
<td align="center">❌</td>
40+
</tr>
41+
<tr>
42+
<th align="center">false</th>
43+
<td align="center">❌</td>
44+
<td align="center">✅</td>
45+
<td align="center">❌</td>
46+
</tr>
47+
<tr>
48+
<th align="center">indeterminant</th>
49+
<td align="center">✅</td>
50+
<td align="center">✅</td>
51+
<td align="center">✅</td>
52+
</tr>
53+
</table>
54+
2655
### Release
2756

2857
A release is any single publication of the JSON Schema specifications (as a group).
@@ -33,7 +62,7 @@ Consecutive releases which maintain compatibility with each other comprise a ver
3362

3463
## Release and Version
3564

36-
The JSON Schema specification will aim to publish annually on or about the first of January each year. Releases are identified by the year they are published.
65+
The JSON Schema specification will aim to publish annually on or about the First of January each year. Releases are identified by the year they are published.
3766

3867
When a new release contains breaking changes, that release begins a new version of JSON Schema.
3968

@@ -69,7 +98,7 @@ https://json-schema.org/1/schema
6998
The latest-release meta-schemas will be updated with proposals as indicated by the [Proposal section](#proposal) of this document.
7099

71100
```diff
72-
@@ These are merely publication URLs. The spec will define the `$id` values for the meta-schemas. @@
101+
@@ These are merely publication URLs. The specification will define the `$id` values for the meta-schemas. @@
73102
```
74103

75104
## Feature Life Cycle
@@ -128,7 +157,7 @@ Tests for the proposal are added to the JSON Schema Test Suite.
128157

129158
Once the initial proposal has been completed, implementations may begin to support the new feature.
130159

131-
Feedback from implementers and users are result in refinements to the proposal, which will then be updated in the implementations.
160+
Feedback from implementers and users are expected to result in refinements to the proposal, which will then be updated in the implementations.
132161

133162
Breaking changes to a proposed feature MAY occur, but are highly discouraged.
134163

@@ -144,15 +173,15 @@ In order to proceed to the next stage ([Stable](#stable)):
144173

145174
Experimental features are not considered to be interoperable across implementations.
146175

147-
If a proposal cannot advance to the next stage, it may be removed. The proposal document is moved to an `archive` subfolder, the keyword is removed from the meta-schemas, and any tests are moved to an `archive` subfolder. The removal of a non-stable feature is not considered a breaking change.
176+
If a proposal cannot advance to the next stage, it may be removed. The proposal document is moved to an `archive` subfolder, the keyword is removed from the meta-schemas, and any tests are moved to an `archive` subfolder. The removal of a feature which has not reached the stable state is not considered a breaking change.
148177

149178
### Stable
150179

151180
The proposal is incorporated into the specification in the `main` branch, and the feature will be required as of the next release.
152181

153182
The appropriate vocabulary meta-schema in the `main` branch is updated to include a subschema that validates the feature's syntax requirements. This will be made available with the next release.
154183

155-
The published meta-schema (for the current release) will have the keyword removed.
184+
Upon publication of the new release, the meta-schema for the lapsed release will have the keyword removed.
156185

157186
The appropriate tests are incorporated into the main suite.
158187

0 commit comments

Comments
 (0)