Document minimal process necessary for the interim release #1368
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| # JSON Schema Specification Development Process | ||
| This document formally defines the process used to evolve the JSON Schema | ||
| specification as of the first stable release in 2023. It applies to the core | ||
| specification and the specifications for any dialects and vocabularies | ||
| maintained by the JSON Schema Org, but it doesn't necessarily apply to | ||
| everything the JSON Schema Org maintains. For example, media type registration | ||
| follows the IETF process. Certain components used within JSON Schema, such as | ||
| Relative JSON Pointer, may also follow a separate process. | ||
|
|
||
| This process doesn't apply to third-party dialects, vocabularies, or other | ||
| extensions. However, third-parties are welcome to use this as a basis for the | ||
| process they use for their specifications. | ||
|
|
||
| _**This process is under development. The details will evolve over time, but | ||
| changes will remain compatible with previous versions of this document.**_ | ||
|
|
||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", | ||
| "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be | ||
| interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). | ||
|
|
||
| ## Canonical URLs | ||
| There MUST be a stable canonical URL for referencing any specification that | ||
| follows this process. If the specification is made available from any other | ||
| URLs, they SHOULD redirect to the canonical URL. If the canonical URL is changed | ||
| in the future, all previous canonical URLs MUST remain accessible as redirects | ||
| to the current URL. | ||
|
There was a problem hiding this comment. When will the URL change? We just finished saying that it's stable. There was a problem hiding this comment. There's no normal reason it should ever need to change. Maybe we choose a URI template to use now and then later we decide that for some reason it would be easier to maintain if we used a different template. This is saying we can do that, but we have to it in a way that won't cause 404s somewhere out on the web. I think it's extremely unlikely that we would ever want to change a canonical URL, but it's there in case some unusual circumstance forces us or we think we have a really good reason. |
||
|
|
||
| ## Compatible Releases | ||
| Everything in the specification is considered "stable" by default and subject to | ||
| compatibility guarantees. Any changes to stable behaviors in the specification | ||
|
There was a problem hiding this comment. I don't think it's a good idea to default to everything being stable -- it will require that we have to be extra-rigorous about finding and marking all the "not yet stable" items for the next release, and if we overlook something, we're screwed. It would be better to default to unstable, and explicitly mark those things we think are now stable. There was a problem hiding this comment. I think default-stable is definitely the place we want to be, but it doesn't have to be the place we start if we think we aren't confident enough to do that yet. It might be best not to say what the default is for now and discuss that separately. |
||
| MUST be backward-compatible with previous versions of the specification and MUST | ||
| NOT change in ways that could be problematic for forward-compatibility. | ||
| Therefore, it's not necessary for implementations to support previous versions | ||
| of the specification separately. | ||
jdesrosiers marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| _Note: How, when, and how often the specification will be updated are all open | ||
| questions that will be decided before any changes are issued following the | ||
| initial release. Because releases are compatible, these things shouldn't effect | ||
jdesrosiers marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| choices made by implementers or schema authors the same way the "draft" releases | ||
| did._ | ||
|
|
||
| ### Experimental Behaviors | ||
| The specification MAY include sections that introduce experimental behaviors. | ||
| These sections MUST be clearly marked and aren't subject to the compatibility | ||
| guarantees of stable features. Experimental behaviors MUST be compatible with | ||
| all current stable behaviors. | ||
|
|
||
| _Note: How and when experimental behaviors are promoted to stable behaviors is | ||
| an open discussion and will be defined before a promotion is considered. The | ||
| process of how an experimental behavior goes from proposal to stable will be | ||
| defined in more detail and is likely to evolve as we learn what works best. Such | ||
| evolution will always be compatible with previous versions of this document._ | ||
|
|
||
| ### Compliance | ||
| Implementations that express support for a particular release MUST support all | ||
| of that release's stable behaviors and SHOULD support any experimental | ||
| behaviors. Because releases are compatible, expressing support for a given | ||
| release implies support for all previous releases (excluding "draft" releases). | ||
|
There was a problem hiding this comment. Just to nitpick, this doesn't necessarily have to be the case "in practice". E.g. if an implementation whitelists dialect identifiers (as most do today), and if each release has a dialect identifier going forward (as is the status quo), but an implementer doesn't remember to add a bunch of old dialect URIs to their implementation (seems likely) to "turn them on", then in practice, the implementation won't actually proceed validating release 2023 if the implementation was written for 2024 and its author forgot to add the 2023 URI to their mapping of "known dialects". In practice I think this actually will indeed happen at various points, so maybe it's mildly nice to weaken this sentence to just say "implies likely support" or something but if you want to leave as-is it's not a big deal either. There was a problem hiding this comment. I don't think we need to account for implementation bugs in the wording here. Bugs happens, but I don't think we need to allow for it, I think we need to consider implementations with those kinds of bugs out of compliance until they fix the bug. Maybe the wording needs to be tweaked to express that better. However, I noticed a related problem. The deprecation section says that implementers "SHOULD" (not "MUST") support deprecated behaviors. If we allow implementations to not support deprecated behaviors, then they aren't in compliance for releases before that behavior was deprecated. The wording here will need to take that into account. |
||
|
|
||
| ### Deprecation | ||
| Stable behaviors MAY be marked as "deprecated". Implementations SHOULD support | ||
| these features to maintain backward compatibility. Deprecated features will | ||
jdesrosiers marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| never be removed from the spec, but schema authors SHOULD migrate away from | ||
| using them as implementations may begin dropping support for these features at | ||
| some point. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What does "stable" mean here? That the URL should never change for a given specification version? or is it also saying that the contents of that URL (the schema itself) must not change? I would tend towards the former, and explicitly state that the contents MAY change from time to time, but only to reflect corrections to mistakes (or to add further refinement to things already in the spec), never to revise the actual intent of validation.
That is:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is only referring to the URL, not the content of what the URL identifies. I'll make an update to try to make that more clear.
All of those points are important for us to decide on and document, but I was expecting to discuss and document those details separately. My goal here is to get down the parts that we can all agree on without major discussion and build from there in separate discussions/PRs. So, at this point, I expect most of this document to be underspecified. In those cases, we are unconstrained for now.