Skip to content

Commit 5501224

Browse files
jdesrosiersgregsdennisJulian
committed
PROCESS: Clarifications and fixes based on feedback
Co-authored-by: Greg Dennis <gregsdennis@yahoo.com> Co-authored-by: Julian Berman <Julian@GrayVines.com>
1 parent 12a8a9a commit 5501224

File tree

1 file changed

+25
-17
lines changed

1 file changed

+25
-17
lines changed

PROCESS.md

Lines changed: 25 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,14 @@
22
This document formally defines the process used to evolve the JSON Schema
33
specification as of the first stable release in 2023. It applies to the core
44
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.
913

1014
## Canonical URLs
1115
There MUST be a stable canonical URL for referencing any specification that
@@ -24,10 +28,14 @@ merged in the last quarter.
2428

2529
## The Stability Model
2630
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.
3139

3240
### Champions
3341
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
4553
discouraged, but may be considered if the feature is optional and disabled by
4654
default.
4755

48-
**Promotion Checklist:**
56+
**Promotion to STAGE-0 Checklist:**
4957
[] Consensus among JSON Schema Org core contributors that the proposal is worth
5058
pursuing
5159
[] 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
5361

5462
### STAGE-0
5563
`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
6371
performance implications. Therefore, these implementations don't need to be
6472
publicly available or have real world use at this point.
6573

66-
**Promotion Checklist:**
74+
**Promotion to STAGE-1 Checklist:**
6775
[] There is general consensus among the core contributors for adding the feature
6876
to the spec
6977
[] Tests are available in the test suite
@@ -73,14 +81,14 @@ publicly available or have real world use at this point.
7381
removes the feature from the `STAGE-0` registry.
7482

7583
### 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`
7785
and are not subject to the compatibility requirements of "stable" features. They
7886
can be added at any time as long as it meets all criteria for `STAGE-1` status.
7987

8088
At this stage, the feature should be seeing real world use. These features MAY
8189
change or be removed all together based on what we learn from real world usage,
8290
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`.
8492

8593
Implementers are encouraged to implement `STAGE-1` features, but are not
8694
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
9199
feature should stay in `STAGE-1` for about one year, but may stay longer if we
92100
don't see it used enough in the wild.
93101

94-
**Promotion Checklist:**
102+
**Promotion to STAGE-2 Checklist:**
95103
[] There is general consensus that the feature has been proven to be a good
96104
addition to JSON Schema and is unlikely to change.
97105
[] 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.
117125

118126
`STAGE-2` features can only be promoted to stable as part of a release.
119127

120-
**Promotion Checklist:**
128+
**Promotion to Stable Checklist:**
121129
[] The vast majority of actively maintained implementations support the feature
122130

123131
### Stable
@@ -148,15 +156,15 @@ Implementations that express support for a particular release MUST support all
148156
features that are stable as of that release.
149157

150158
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.
152160

153161
## Meta-Schemas
154162
Meta-schemas associated with the specification(s) maintained under this process
155163
are subject to the same compatibility rules as the specification. They can be
156164
updated at any time, but changes MUST be backward compatible and allow for
157165
forward compatibility with future schemas.
158166

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
160168
MUST remain available and redirect to the new URI.
161169

162170
Meta-schemas are considered non-normative. It's sometimes not possible or not

0 commit comments

Comments
 (0)