From 04b07a897ee3d0c35229a19222b25973f178702a Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 14 Nov 2022 09:20:34 -0800 Subject: [PATCH 1/5] Document minimal process for interim release --- PROCESS.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 PROCESS.md diff --git a/PROCESS.md b/PROCESS.md new file mode 100644 index 00000000..888a073f --- /dev/null +++ b/PROCESS.md @@ -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. + +## Compatible Releases +Everything in the specification is considered "stable" by default and subject to +compatibility guarantees. Any changes to stable behaviors in the specification +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. + +_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 +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). + +### Deprecation +Stable behaviors MAY be marked as "deprecated". Implementations SHOULD support +these features to maintain backward compatibility. Deprecated features will +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. From 5a16e2d55de8e01120aeee13746049403f8ff2e4 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 20 Dec 2022 14:03:29 -0800 Subject: [PATCH 2/5] PROCESS: Update with feedback from Julian --- PROCESS.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 888a073f..df3d7d3e 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -31,18 +31,18 @@ compatibility guarantees. Any changes to stable behaviors in the specification 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. +of the specification separately (excluding "draft" releases). _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 +initial release. Because releases are compatible, these things shouldn't affect 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 +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 @@ -56,10 +56,11 @@ 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). +Support for previous releases might have limitations if an implementation +chooses not to support a deprecated behavior. ### Deprecation Stable behaviors MAY be marked as "deprecated". Implementations SHOULD support -these features to maintain backward compatibility. Deprecated features will -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. +these behaviors to maintain backward compatibility. Schema authors SHOULD +migrate away from using deprecated behaviors as implementations MAY begin +dropping support for these behaviors at some point. From f019cfd8b83203680b85ec0551e4b78c9816a16e Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 27 Dec 2022 17:55:53 -0800 Subject: [PATCH 3/5] PROCESS: Updates addressing Austin's feedback --- PROCESS.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index df3d7d3e..66b1f7ca 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -29,15 +29,11 @@ to the current URL. Everything in the specification is considered "stable" by default and subject to compatibility guarantees. Any changes to stable behaviors in the specification 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 (excluding "draft" releases). +NOT change in ways that could be problematic for forward compatibility. _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 affect -choices made by implementers or schema authors the same way the "draft" releases -did._ +initial release._ ### Experimental Behaviors The specification MAY include sections that introduce experimental behaviors. @@ -52,15 +48,19 @@ 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). -Support for previous releases might have limitations if an implementation -chooses not to support a deprecated behavior. +An implementation is compliant with a given release if it implements all of the +required stable behaviors defined in that release. Experimental behaviors are +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 +previous releases might have limitations if an implementation chooses not to +support a deprecated behavior. ### Deprecation -Stable behaviors MAY be marked as "deprecated". Implementations SHOULD support -these behaviors to maintain backward compatibility. Schema authors SHOULD -migrate away from using deprecated behaviors as implementations MAY begin -dropping support for these behaviors at some point. +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. From 3cea49754ce1a9eabe0cdab3cd2a1473ed8df96c Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 5 Jan 2023 11:08:23 -0800 Subject: [PATCH 4/5] PROCESS: Updates from Karen's feedback --- PROCESS.md | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 66b1f7ca..3584a17a 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -19,11 +19,11 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 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 MUST be a canonical URL for referencing the current version of 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. ## Compatible Releases Everything in the specification is considered "stable" by default and subject to @@ -35,6 +35,15 @@ _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._ +Compatibility is defined with respect to the true/false validation result of a +schema. If an instance is valid or invalid against a schema according to one +release, all other releases including future releases MUST define the same +validation result or be indeterminate. An indeterminate result is neither valid +nor invalid. + +_Note: Additional compatibility constraints may be added in the future such as +output format results._ + ### Experimental Behaviors The specification MAY include sections that introduce experimental behaviors. These sections MUST be clearly marked and aren't subject to the compatibility @@ -49,18 +58,18 @@ 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 -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. +required stable behaviors in that release. Experimental behaviors are 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 -previous releases might have limitations if an implementation chooses not to -support a deprecated behavior. +Because releases using this process are compatible, expressing support for a +given release implies support for all previous releases (excluding "draft" +releases). Support for 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. +Behaviors MAY be marked as "deprecated". Implementations are expected to support +stable deprecated behaviors to maintain backward compatibility and schema +authors should migrate away from using these behaviors. From 7bc830756680295f3a5ea8882faabb9474e86584 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 5 Jan 2023 14:31:57 -0800 Subject: [PATCH 5/5] PROCESS: Update to remove experimental and deprecated --- PROCESS.md | 36 +++--------------------------------- 1 file changed, 3 insertions(+), 33 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 3584a17a..dedb23be 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -26,7 +26,7 @@ URL is changed in the future, all previous canonical URLs MUST remain accessible as redirects to the current URL. ## Compatible Releases -Everything in the specification is considered "stable" by default and subject to +Any part of the specification that is considered "stable" is subject to compatibility guarantees. Any changes to stable behaviors in the specification MUST be backward-compatible with previous versions of the specification and MUST NOT change in ways that could be problematic for forward compatibility. @@ -38,38 +38,8 @@ initial release._ Compatibility is defined with respect to the true/false validation result of a schema. If an instance is valid or invalid against a schema according to one release, all other releases including future releases MUST define the same -validation result or be indeterminate. An indeterminate result is neither valid -nor invalid. +validation result or define the result to be indeterminate. An indeterminate +result is neither valid nor invalid. _Note: Additional compatibility constraints may be added in the future such as output format results._ - -### 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 in that release. Experimental behaviors are 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 using this process are compatible, expressing support for a -given release implies support for all previous releases (excluding "draft" -releases). Support for previous releases might have limitations if an -implementation chooses not to support a deprecated behavior. - -### Deprecation -Behaviors MAY be marked as "deprecated". Implementations are expected to support -stable deprecated behaviors to maintain backward compatibility and schema -authors should migrate away from using these behaviors.