Nov 28, 2022 · Nov 3, 2022 · Nov 8, 2022 · Nov 8, 2022 · Nov 14, 2022 · Nov 14, 2022
diff --git a/adr/2022-11-stable-spec.md b/adr/2022-11-stable-spec.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,180 @@
	# Selecting a new specification development process

	* Status: accepted
	* Deciders: @jdesrosiers @relequestual @awwright @handrews @gregsdennis
	* Date: 2022年11月02日

	## Context and Problem Statement
	We've chosen to decouple our process from IETF, so we need to choose a new
	specification development process to replace it.

	## Decision Drivers
	* Dropping the "draft" label is an important driver of this change. It's mostly
	an artifact of the IETF process and has proven to be confusing for the
	community.
	* The community wants a stable version of JSON Schema.
	* There is a need for JSON Schema to continue to evolve to meet evolving
	needs.
	* There is a demand for custom keywords/vocabularies/dialects and we want to
	continue to support those use cases.
	* There is a need to ease the burden of implementations supporting multiple
	versions of JSON Schema.

	## Considered Options
	There have been two proposals put forward. Both address the goal of a stable
	specification with the ability to evolve. The third option represents sticking
	with the status quo.

	### Option 1 - TC-39 inspired
	The spec would be converted from I-D XML to Markdown, but can otherwise be
	structured however we choose. A system would be put in place to allow us to flag
	the stability level of any feature in the spec. There would be only one version
	of the spec and that version can change at any time, but changes to stable
	features must follow strict backward and forward compatibility requirements.

	New features must go through a hardening process to ensure that they are very
	unlikely to change before they are considered stable and subject to
	compatibility requirements. This process will impose strict requirements
	including tests, implementations, documentation, and real world vetting before a
	feature or new keyword can be made stable in the spec.

	Since the spec is constantly evolving, a "release" is just a matter of promoting
	unstable features to "stable" status. Releases would happen once a year and be
	designated by the year they were released.

	### Option 2 - IETF Inspired
	The spec would be reorganized into two parts: "Core Semantics" and "Standard
	Extensions".

	The "Core Semantics" spec would contain the bare minimum rules that
	must be implemented for validators to not produce inaccurate results regardless
	of future revisions or extensions. Among other necessities, this would include a
	core set of keywords necessary to fully support structural validation and an
	extension mechanism. This spec should be considered stable and should rarely
	change, but if it does, it must do so in a backward and forward compatible way.
jdesrosiers marked this conversation as resolved. Outdated Show resolved Hide resolved

	The "Standard Extensions" spec would include the rest of the spec. Features and
	keywords included in this spec are so ubiquitous that they should be considered
	essential for implementations to support. Changes to this spec must be
	compatible with previous releases with exceptions only in extreme cases.

	A registry could be maintained that maps keywords to their specified semantics.
	User extensions that aren't in the registry should use a URI for their keyword
	to avoid conflicts with other third-party extensions or with future standard
	extensions.

	### Option 3 - Minimal Change
	Option 3 represents the minimal amount of change to our process from what we
	have been doing. The spec would need to be converted from I-D XML to a Markdown
	version that would be served on the website, but otherwise we would continue to
	work the way we have been. We would aim for new version release every year with
	a patch release mid-cycle. Each release is a distinct version of JSON Schema and
	has no compatibility guarantees between versions.

	## Decision Outcome
	The decision is to go with Option 1 while leaving discussion open for nearly all
	of Option 2 because it is mostly compatible with Option 1. Option 2 uses an
	immutable spec where each release replaces the last while the Option 1 uses a
	mutable spec. The outcome of having only one current version of the spec is
	achieved with either option, but the mutable spec allows us to remove some
	unnecessary roadblocks in our development processes and allows us to release a
	stable spec much sooner. Other than that, discussion for the rest of Option 2
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved
	can continue within the constraints of Option 1.

	Option 1 puts no constraint on the structure of the spec and restructuring is
	allowed at any time as long as it doesn't break compatibility requirements.
	Therefore, restructuring the spec as "Core Semantics" and "Standard Extensions"
	is compatible with Option 1. We can move forward with Option 1 now while leaving
	the restructuring discussion open.

	Option 2 defines a new extension mechanism and some new keywords. These features
	can be introduced under the stability model described in Option 1. Therefore, we
	can move forward with Option 1 while leaving the discussion open for these new
	features.
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved

	## Pros and Cons of the Options
	The biggest benefit is shared between Option 1 and Option 2. Both approaches
	result in a stable spec. This will have benefits implementers and users. Because
	of the compatibility requirements, whenever you write a schema, you will never
	need to change it just to keep up with new features added to JSON Schema. This
	is also better for implementers because they don't have to maintain separate
	code different semantics in different versions. They just need to code for the
jdesrosiers marked this conversation as resolved. Outdated Show resolved Hide resolved
	current release and they will automatically have support for past releases.

	### Option 1 - TC-39 Inspired
	The two things that make this option stand out are the stability model and the
	mutability of the spec document.

	Having a mutable spec allows us to make clarifications and bug fixes immediately
	rather than having to wait months or years for the next release to go out. It
	also allows us to iterate faster on unstable features which would allow us to
	get them to a stable state much sooner. For example, we have changes to dynamic
	references that have been agreed upon and ready to go for over a year, but users
	can't benefit from the change until we can get the next full release published.
	With this model, the change could have been made available for over a year now
	and we would have a years worth of feedback on it's use. Having a mutable spec
Comment on lines +107 to +113 Copy link Member @Relequestual Relequestual Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Thinking/spitballing: In such a situation, how would a user be able to determine if an implementation supported the RIGHT version of an unstable feature? Should we provide guidance that says something like unstable features should be referenced by implementations by the specific commit date of the spec file and tests (if any) they are intending to implement? That got me thinking further... If we specified that pre-stable keywords MUST be postfixed with the date of the commit, or stage number, or something, idk, then you make sure users and implementations can differenciate easily between pre-stable and stable versions of that keyword. Although I guess you'd expect to be able to do this with the "release" dialect. And, I wonder if this is somewhat a moot point if we prevent non-dialect/vocabulary defined keywords from being used. Copy link Member Author @jdesrosiers jdesrosiers Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. This is a bit out of scope for this PR, so let's have this discussion elsewhere.
	also allows us to introduce new features without having to wait for a release.
	For example, the `propertyDependencies` keyword has also been waiting for months
	for a release. Users could have been benefiting from it for months and providing
	feedback.

	The downside of a mutable spec is that it can be more difficult for implementers
	and users to track when changes happen. We will need to be better at
	communicating changes in blog posts or equivalent.
Comment on lines +119 to +121 Copy link Member @Relequestual Relequestual Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. I have some automation ideas on this. Any such concept though would require us to track "latest modified" status of keywords in a structured data file, so automation can be run against such data. This would add a burden to spec authors, unless unstable features/keywords are written in individual files, and merged into a single spec artifact at workflow time. In which case, changes would be easier to catch, but you still wouldn't know if it was a change requiring implementation change or not unless a human specified such. Copy link Member Author @jdesrosiers jdesrosiers Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. This is a bit out of scope for this PR, but I think I'd argue that this communication is better done by a person than an automation. An automation can't explain why something changed. Copy link Member @gregsdennis gregsdennis Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Automation could provide reminders for one of us to post on a change, though. jdesrosiers reacted with thumbs up emoji

	The stability model allows us to ensure we don't make incompatible changes to
	stable features, but it also allows us to introduce new features and get real
	world feedback without committing to full compatibility requirements. This makes
	it much more likely that we don't get stuck with something that doesn't work out
	or could be done better.

	The stability model also makes it clear to users which features are stable and
	how likely an unstable feature is to change in the future. Whether they prefer
	to stick with stable features or want to use a new keyword, users have the
	information they need to make that decision.

	The downside of the stability model is that it presents a very high barrier for
Copy link Member @Relequestual Relequestual Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. It's debatable if a high barrier is a downside. If stability is the goal, a high barrier can actually be a benefit. Copy link Member Author @jdesrosiers jdesrosiers Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. I agree. I thought I had addressed that in previous paragraphs, but it seems I only implied it and should be more clear. The high barrier is definitely a benefit, but there's always a trade off. I was trying to address the trade off in this paragraph. I'll try to make it more clear. Copy link Member @gregsdennis gregsdennis Nov 14, 2022 • edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. To the point of there being a high barrier, when I decided to create JsonSchema.Net as a replacement for Manatee.Json, there was a LOT of work to do, and the vast majority of it was re-implementing all of the keywords. This high barrier was a serious factor in my consideration of making a new library. (Obviously I decided to do it, but I did have to think about the workload I was taking upon myself.) It's definitely less of a burden for existing libraries to update than for a new library to be created. Copy link Member Author @jdesrosiers jdesrosiers Nov 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Right. Although it creates high barriers for spec changes, it actually lowers the barrier for implementers, which is probably worth mentioning as well.
	a feature to make it into a stable status. It would typically take two years for
	a feature to reach stability which could be a long time to wait for users who
	need to stick to the stable feature set but could benefit greatly from a new
	feature.

	### Option 2 - IETF Inspired
	The benefit of this approach is that it's compatible with the IETF process
	without imposing some of the constraints and perception issues that we had with
	IETF. We can pursue an RFC in the future if we choose to without significant
	changes or spec restructuring.

	With this proposal, releases are done as a new document that replaces the
	previous documents. Compared to the constantly evolving spec in Option 1, change
	from non-functional clarifications and bug fixes to adding and evolving new
	features takes much longer if you have to wait for the next release to make a
	change. This lengthens the feedback loop slowing spec development progress.
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved

	The main downside of this approach compared to Option 1 is that it will likely
	take quite a while to get to a stable release. The spec restructuring is
	controversial and it proposes several new keywords that are also controversial.
	Discussing, achieving consensus, specifying, and implementing these changes will
	take time. Introducing new features and keywords is much more risky with the new
	compatibility requirements, so we have to go extra slow to make sure we get it
	right.

	### Option 3 - Minimal Changes
	The benefit of this solution is that we don't have the overhead of defining
	and/or learning a new process. In the short term, we can put more effort into
	improving JSON Schema if we don't have the distraction of defining a whole new
	process. The problem with this approach is that it doesn't solve the problem
	with the "draft" label and doesn't provide the stability the community is
	looking for.

	## Links
	* https://github.com/jdesrosiers/json-schema-spec/blob/main/adr/2022-09-decouple-from-ietf.md -
	The ADR for the decision to decouple from IETF
	* https://github.com/orgs/json-schema-org/discussions/234 - Proposal submitted
	by @jdesrosiers for a process to replace the IETF based process we'd been
	using.
	* https://github.com/orgs/json-schema-org/discussions/257 - @awwright's vision
	for JSON Schema including how it can continue to evolve while still having a
	stable core.
	* https://github.com/json-schema-org/community/discussions/119 - When we first
	started talking about forward compatibility and a stable spec.
jdesrosiers marked this conversation as resolved. Show resolved Hide resolved