Skip to content

Add ADR for decoupling from IETF #1277

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

Merged
merged 11 commits into from
Sep 27, 2022
Merged

Add ADR for decoupling from IETF #1277

Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f00f9ea
Add ADR for decoupling from IETF
jdesrosiers Aug 17, 2022
6062b8f
Update adr/2022-08-decouple-from-ietf.md
jdesrosiers Aug 18, 2022
d5befa5
Update adr/2022-08-decouple-from-ietf.md
jdesrosiers Aug 18, 2022
0064831
Update adr/2022-08-decouple-from-ietf.md
jdesrosiers Aug 18, 2022
789ae60
ADR decouple from IETF draft 2
jdesrosiers Aug 18, 2022
dd3c640
ADR decouping from IETF draft 3
jdesrosiers Aug 23, 2022
f96af8a
ADR decouping from IETF draft 4
jdesrosiers Sep 6, 2022
610a388
ADR decoupling from IETF draft 5
jdesrosiers Sep 7, 2022
9bbde03
ADR decoupling from IETF draft 6
jdesrosiers Sep 8, 2022
2eaf95a
Add comments about W3C being a pay to play standards org
Relequestual Sep 26, 2022
9da7e23
Add Greg to IETF decouple ADR
Relequestual Sep 27, 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
137 changes: 137 additions & 0 deletions adr/2022-08-decouple-from-ietf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
# Decoupling from IETF

* Status: accepted
* Deciders: @jdesrosiers @relequestual @awwright
* Date: 2022-08-17

Related Issues:
* https://github.com/orgs/json-schema-org/discussions/69 - This issue is about
dropping the "draft" prefix from our releases. This ADR doesn't cover that,
but much of the discussion about whether or not to decouple from IETF is in
that discussion.
* This topic has been discussed in many other places as well that are difficult
to link to here including Slack, Twitter, OCWMs, and conference discussions.

## Context and Problem Statement

Currently JSON Schema loosely follows the IETF Internet-Draft (I-D) process for
spec development and releases but isn't associated with any IETF working group.
JSON Schema is an individual draft. That means it isn't on a standards track
with IETF and IETF is not involved nor supports the spec in any way other than
hosting the canonical version of our I-Ds. Our perceived involvement with IETF
causes confusion and misunderstanding within our community in the cases were our
practices and the realities of our situation deviate from a typical IETF I-D
lifecycle. The thing that makes our situation different than a typical I-D is
that our "drafts" are intended for use in production.

## Decision Drivers

* IETF's draft versioning system doesn't work for JSON Schema and we stopped
using it to version our releases a while ago. We now use date based versioning
and even have more than one draft submission per release (the initial release
and the patch release).
* The IETF process is optimized for working on a draft until it's done and then
disbanding. In some cases, the RFC may be revisited and revised in the future,
but this is rare and generally contains little more than clarifications and
reference updates. JSON Schema is not like that. JSON Schema is more like a
programming language. When it stops evolving, it will lose its relevance.
When we finish a release of JSON Schema, we don't disband, we start work on
the next release.
* Every one of our releases is expected to be used in production and will be
depended on for many years forward. This is not consistent with normal IETF
drafts. Even if we don't publicly use the term "draft", we're still using the
IETF I-D system in a way that's not intended.
* Under IETF, JSON Schema fits under the category of "draft". The community has
repeatedly told us that they perceive this to meant that JSON Schema
"incomplete" and not "not ready for production use". This is the wrong message
for us to be sending as all of our releases are intended to be used in
production. This ADR doesn't decide whether or not to drop the "draft" from
our releases, but decoupling from IETF gives us that option.
* Several members of the JSON Schema team have had poor interactions with IETF
and don't feel that working with them would be productive. This is a
relatively minor consideration. If we thought IETF was right for JSON Schema,
Copy link
Contributor

Choose a reason for hiding this comment

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

Since this is going to be a formal public document, I've been thinking about this wording. I'm also going to explain some things here because they keep getting asked (most recently by @devinbost), so I spent a few hours tracking down the history. Skip down to the last section for wording recs.

Contacting the old JSON working group

When I contacted the JSON working group in January 2018 (see #526), this quite helpful response from Paul Hoffman indicated some likely difficulties:

There appears to be interest in something around schema for JSON; it is
not clear if there is interest in starting from the specific spec at
https://github.com/json-schema-org/json-schema-spec. I bet there is some
interest in that, and some interest in something else. This is quite
typical of requests for the IETF to adopt work that originated outside
the IETF, with mixed results in any of of "adopt with the intention of
making only minor changes", "adopt and make major changes", and "start
from scratch while getting inspiration from the existing work".

While the above paragraph suggests that maybe we could have gotten it adopted, there were zero encouraging responses or expressions of interest aside from Paul's response. There were several non-productive criticisms and dismissals on such topics as not needing minimum other than 0 or 1, and not needing maximum at all. Of course, individual poor-quality feedback is not necessarily representative, but it was the lack of anything resembling constructive engagement was the more important concern. Sadly I can't link to the absence of something.

In response to that discussion, someone else brought up a project called JSON Content Rules, which got much more interest (although notably, no further drafts were ever produced and the project was abandoned). Somewhat later, the project that eventually became JSON Type Definition also got more attention (although note that it is an "experimental" RFC and was never adopted by a working group).

The important point here is not that some people were grumpy and hostile (I'm... really not in a position to throw stones there), it's that no one was actively interested, and instead those who participated actively favored other projects.

The JSON Path experience

While I don't want to put anyone on the spot, we do know that JSON Path's adoption by a working group has led to more changes in that specification than were expected or wanted by at least some participants. It essentially illustrates the fear discussed above: that the momentum would be away from what works for our existing user community.

Of course, that doesn't meant the same thing would happen, but it is very relevant (and involves some overlap of people).

A perusal of email archives and GitHub issues and PRs also reveals a number of incompatible expectations in working styles and process. Whether or not this qualifies as a "negative experience" depends on one's expectation, but it would probably be negative for us.

Suggested wording

I would suggest replacing the "poor interactions" wording with something like:

Several members of the JSON Schema team have interacted with JSON-related IETF working groups. Some of these interactions demonstrated an indifference or hostility to JSON Schema, and a preference for projects taking a different approach. Equally important was a lack of any active interest or constructive engagement. Finally, we were informed that any schema project for JSON would not necessarily start from JSON Schema as a base, indicating that a "JSON Schema" working group would quite likely not involve JSON Schema itself. This impression has been reinforced by observing the amount of change introduced to JSON Path as a consequence of its adoption by an IETF working group. While we have a good relationship with the relatively new HTTPAPIs working group, the combination of these other experiences with other mismatches between our project and the IETF process contributes to our reluctance to move forward through the iETF.

Copy link

Choose a reason for hiding this comment

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

While the above paragraph suggests that maybe we could have gotten it adopted, there were zero encouraging responses or expressions of interest aside from Paul's response. There were several non-productive criticisms and dismissals on such topics as not needing minimum other than 0 or 1, and not needing maximum at all. Of course, individual poor-quality feedback is not necessarily representative, but it was the lack of anything resembling constructive engagement was the more important concern. Sadly I can't link to the absence of something.

@handrews , in reviewing the mail archives you provided and acquainting myself with the references to criticisms posed it only reinforces the decision to go in a different direction. The criticisms of minimum or maximum, for example, I patently would not support. In the IEC standards we're working on we have a distinct need for exactly such keywords to properly define the contextual model mappings into JSON schema syntax. This is "real world stuff". I don't think valuable time/energy should be spent arguing fundamental constructs such as these in the spec.

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 using the suggestion. A first-hand account is much preferred to my second-hand account.

we could find ways to make those relationships work. We have a good
relationship with the relatively new HTTPAPIs working group and working with
them would be far more likely to be productive than the people/WG we were
previously in communication with.

## Considered Options

1. Continue to submit I-Ds, while using our customized process with no intention
of pursing standards track RFC status.
2. Go all-in with IETF and pursue a standards track RFC with the IETF. The
approach would be to describe the essential characteristics of evaluating a
JSON Schema: the keywords that everybody is guaranteed to support, and any
extension mechanisms.
3. Join W3C and pursue a standards track with them using their process.
4. Decouple completely from any standards organization and come up with our own
specification development lifecycle (SDLC) model inspired by well established
projects with an SDLC that more closely meets or needs.

## Decision Outcome

Our decision is to go with Option 4 and decouple from standards organizations
that don't fit our needs. We don't currently have a plan for what to replace
IETF with, but we are currently investigating how other established projects do
their SDLC and will likely choose one to emulate and adapt to our needs.
Although we don't have a replacement solution in place yet, we are confident
that continuing to abuse the IETF I-D process or conforming to a standards
organization process that doesn't fit our needs is not the way to go.

Option 2 and 3 are still on the table if we feel it makes sense when we get to a
more stable place in the future. The main concern is the pain this process is
causing while we are in this unusual phase of simultaneous unstable growth and
production use. Standardization isn't out of the question, it's just not
productive for us to be developing JSON Schema within the constraints of a
standards organizations procedures.

Option 1 was rejected because it ignores the problems we've been facing and
provides no solution. No one wants this.

Option 2 was rejected for several reasons. If we go all in with IETF, we would
have to join a working group and treat JSON Schema like a normal I-D. That means
we would have to start treating drafts as drafts, which means not recommending
production use until we are ready for RFC and not releasing a new
production-ready version of JSON Schema until we've reached RFC status. Most of
the core contributors don't believe that we are close enough to an RFC-ready
release that we want to commit to not being able to issue another release until
that happens.

There are other concerns including skepticism that even with an extension
mechanism that the RFC wouldn't need regular updates, which is not normal
practice for an RFC and would require significant effort to issue a replacing
RFC. Without a concrete proposal on the scope of the RFC and the extension
mechanisms, it's hard to commit to this path.

Additionally, many of the core contributors have found working with the IETF
unproductive and have concerns about JSON Schema getting deeper involved without
compelling enough reason. Most agree that the reasons are not sufficiently
compelling at this point.

Option 3 was rejected because it has the same problems as Option 2 accept that
we don't have the same unpleasant history with W3C than we do with IETF.

### Positive Consequences

* Decoupling from IETF allows us to distance ourselves from the assumptions that
people make about JSON Schema because they assume it works like a typical I-D.
* Decoupling from IETF allows us to customize our SDLC model to what works best
for JSON Schema.

### Negative Consequences

* Not being associated with a recognized standards organization such as IETF,
W3C, or IEEE reduces the credibility of JSON Schema in the eyes of some.
However, we have received feedback from people involved in standards
development that say they are comfortable adopting OpenAPI without it being
associated with a standards organization, so we don't expect this to be a
Copy link
Contributor

Choose a reason for hiding this comment

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

This was said in the context of the connection with the Linux Foundation, not simply OpenAPI as a completely independent entity. Which still works as we are also connected. But it's important to keep the focus on connection to some sort of larger organization here.

Copy link
Member Author

Choose a reason for hiding this comment

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

It didn't appear to me that the answer to OpenAPI's approach being acceptable was related to or contingent on their connection with the Linux Foundation. Those appeared to be two separate answers to two separate questions. Considering that the Linux Foundation has nothing to do with standards development or publishing, it's hard to see how the two are related. However, I do see how association with the Linux Foundation provides credibility in the general sense and is therefore worth mentioning in this context.

Copy link
Contributor

Choose a reason for hiding this comment

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

However, I do see how association with the Linux Foundation provides credibility in the general sense and is therefore worth mentioning in this context.

Yes, that's what I was trying to get at, thank you for figuring that out despite my poor articulation!

Copy link

@ucaiug-admin ucaiug-admin Sep 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

This was said in the context of the connection with the Linux Foundation, not simply OpenAPI as a completely independent entity. Which still works as we are also connected. But it's important to keep the focus on connection to some sort of larger organization here.

Agreed Henry. Thanks for calling out this point. It's an important aspect of how things will be perceived as the JSON schema spec is utilized as a dependency in other standards.

significant issue for JSON Schema either.
* If we don't go the standardization route with IETF or W3C, we lose access to
their expert review process.
* One of the benefits of an RFC is other standards can normatively reference it,
and use JSON Schema to define their JSON-based syntaxes. Independently
publishing a specification does not permit this.
* Defining our own SLDC process will be a lot of work and none of us have
expertise in defining such a process. However, we can take inspiration from
existing well established projects and we would have the freedom to update our
process as we learn what works and what doesn't.