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,66 @@ | ||
| # 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. | ||
|
Comment on lines
+31
to
+32
There was a problem hiding this comment. I'm not really sure how you're defining forward- and backward-compatible here. Some examples might help. |
||
|
|
||
| _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._ | ||
|
Comment on lines
+34
to
+36
There was a problem hiding this comment. We could instead just say "new specification versions shall be released from time to time on a schedule still to be determined", which leaves us much more flexibility later as to what process to adopt. There was a problem hiding this comment. I'm not seeing how that's different than what the text already says. |
||
|
|
||
| ### 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 behaviors. 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 | ||
| An implementation is compliant with a given release if it implements all of the | ||
| required stable behaviors defined in that release. Experimental behaviors are | ||
|
There was a problem hiding this comment. This sentence implies that stable items are explicitly defined (which is what I think we should do, but not what this document states). There was a problem hiding this comment. I don't think that sentence implies anything about how stable items are defined, but I'll see if I can make it less ambiguous. Is it the word "required" that makes you interpret it that way? I included that to make it clear that an optional feature (like the annotation-assertion vocabulary) doesn't need to be implemented even though it's a stable feature. |
||
| not required to be considered compliant, but implementing them is highly | ||
| encouraged. An implementation that implements behaviors that are not compatible | ||
| with the given release is considered compliant only if those behaviors are | ||
| disabled by default. | ||
|
|
||
| Because releases are compatible, expressing support for a given release implies | ||
| support for all previous releases (excluding "draft" releases). Support for | ||
|
There was a problem hiding this comment. But this isn't true right now. It may be true in the future, when we figure out what "backwards compatible" means, but that's premature for this set of changes. There was a problem hiding this comment. I'll try to make it more clear. This document applies only to releases that were produced using this process. |
||
| previous releases might have limitations if an implementation chooses not to | ||
| support a deprecated behavior. | ||
|
|
||
| ### Deprecation | ||
| Stable behaviors MAY be marked as "deprecated". Implementations are expected to | ||
| support these behaviors to maintain backward compatibility and schema authors | ||
| should migrate away from using these behaviors. | ||
|
There was a problem hiding this comment. Unstable things could also be deprecated - e.g. "we put this in as an experiment, and it didn't work out, so we're going to remove it in the next release". There was a problem hiding this comment. I hadn't thought about using deprecation that way. Deprecation is one of the things we know needs more discussion. I'll try to reword the current text in a way that doesn't restrict us from deciding to use it that way. |
||
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.