Skip to content

Document minimal process necessary for the interim release #1368

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

Document minimal process necessary for the interim release #1368

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
04b07a8
Document minimal process for interim release
jdesrosiers Nov 14, 2022
5a16e2d
PROCESS: Update with feedback from Julian
jdesrosiers Dec 20, 2022
f019cfd
PROCESS: Updates addressing Austin's feedback
jdesrosiers Dec 28, 2022
3cea497
PROCESS: Updates from Karen's feedback
jdesrosiers Jan 5, 2023
7bc8307
PROCESS: Update to remove experimental and deprecated
jdesrosiers Jan 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions PROCESS.md
View file
Open in desktop
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
Copy link
Member

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:

  • we found an error in the schema that doesn't match the spec. it is acceptable to revise the schema to properly reflect what the spec says.
  • something wasn't in the schema because we didn't see a way of expressing a particular thing in the spec, but then later we see a way of doing so. it is acceptable to revise the schema to add the new check.
  • we issue a minor revision to the spec (e.g. to clarify a point that was vague before). it is acceptable to add something to the schema to express this clarification.
  • we change our mind about how a keyword works, which contradicts the current spec. it is NOT acceptable to make this change in the current schema - it needs to be deferred to the next major release.

Copy link
Member Author

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.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When will the URL change? We just finished saying that it's stable.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence implies that stable items are explicitly defined (which is what I think we should do, but not what this document states).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.