Skip to content
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

Add ADR for choosing a new SDLC #1346

Merged
merged 5 commits into from
Nov 28, 2022
Merged

Add ADR for choosing a new SDLC #1346

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
522d01d
Add ADR for choosing a new SDLC
jdesrosiers Nov 3, 2022
1a8b62b
Apply suggestions from code review
jdesrosiers Nov 8, 2022
2779b22
ADR SDLC - Improve Option 2 description
jdesrosiers Nov 8, 2022
771b839
Update adr/2022-11-stable-spec.md
jdesrosiers Nov 14, 2022
46c4665
ADR SDLC - Improve wording about slow path to stable
jdesrosiers Nov 14, 2022
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
108 changes: 53 additions & 55 deletions adr/2022-11-stable-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ 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
### 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
Expand All @@ -44,66 +44,64 @@ designated by the year they were released.

### Option 2 - IETF Inspired
The spec would be reorganized into two parts: "Core Semantics" and "Standard
Extensions".
Extensions". Changes to either spec are subject to strict backward and forward
compatibility requirements and would be released as a new spec that replaces and
obsoletes past versions of the spec.

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

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.
extension mechanism. This spec should rarely change. New features would be added
through additional specifications that define extensions to the "Core Semantics"
spec.
Comment on lines +55 to +57
Copy link
Member

Choose a reason for hiding this comment

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

👍


The "Standard Extensions" spec is an example of one of these extension
specifications. This spec would be authored by the JSON Schema Org, but
extension specifications could be authored by anyone. The "Standard Extensions"
spec would include everything from the current spec that isn't included in the
"Core Semantics" spec. Features and keywords included in this spec are so
ubiquitous that they should be considered essential for implementations to
support.

### 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
work the way we have been. We would aim for new version releases every year with
patch releases 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
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.
The decision is to go with Option 1 while leaving discussion open for aspects of
Option 2 that could be adopted within the constraints of Option 1.

Option 2 uses an immutable spec where each release replaces the last while
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.

Option 2's restructuring of the spec into "Core Semantics" and "Standard
Extensions" isn't specifically ruled out, but spec evolution is expected to be
done primarily through mutation of the spec guided by the stability process
rather than through extension. 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.

## 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
current release and they will automatically have support for past releases.
result in a stable spec. This will have benefits for both 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 changes to JSON Schema.
This is also better for implementers because they don't have to maintain
separate code with different semantics in different versions. They just need to
code for the 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.
The two things that make this option stand out are the stability model governing
spec evolution 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
Expand All @@ -129,9 +127,9 @@ 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.
how likely a 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

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

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

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
Expand All @@ -142,14 +140,14 @@ 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.
our previous process. 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.
previous documents. Compared to the constantly evolving spec in Option 1,
changes 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.

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
Expand Down