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

Jump to bottom

Add ADR for decoupling from IETF #1277

Merged
merged 11 commits into from
Sep 27, 2022
Merged

Add ADR for decoupling from IETF #1277

Changes from 1 commit
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
82 changes: 82 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,82 @@
# Decoupling from IETF

* Status: accepted
* Deciders: @jdesrosiers @relequestual @awwright
jdesrosiers marked this conversation as resolved.
Show resolved Hide resolved
* 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 follows the IETF Internet-Draft (I-D) process for spec
development and releases but aren't associated with IETF in any way. Our
perceived involvement with IETF causes confusion and misunderstanding within our
community in the cases were our needs and the realities of our situation deviate
from the IETF process.

## 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 a date based version
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 loose it's relevance.
jdesrosiers marked this conversation as resolved.
Show resolved Hide resolved
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
handrews marked this conversation as resolved.
Show resolved Hide resolved
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.

## Considered Options

1. Continue to submit I-Ds, while using our customized process with no intention
of pursing standards track RFC status.
2. Get JSON Schema to a stable place and pursue a standards track RFC with the
IETF.
3. Decouple from IETF completely and come up with our own governance model.
handrews marked this conversation as resolved.
Show resolved Hide resolved

## Decision Outcome

Our decision is to go with Option 3 and decouple from IETF completely and come
up with our own governance model. The idea of having the come up with our own
jdesrosiers marked this conversation as resolved.
Show resolved Hide resolved
governance model is daunting, but when the alternatives are to continue to abuse
the I-D process or to conform to the IETF process that doesn't fit our needs,
going our own way seems the bast option.
jdesrosiers marked this conversation as resolved.
Show resolved Hide resolved

### 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 governance model to what works
best for JSON Schema.

### Negative Consequences

* Choosing our own governance model means we aren't associated with a recognized
standard body which could reduce to credibility of JSON Schema in the eyes of
some.
handrews marked this conversation as resolved.
Show resolved Hide resolved
* If we don't go the standardization route with IETF, we lose access to their
expert review process.
* Defining our own process will be a lot of work and none of use have expertise
in defining such a process.
jdesrosiers marked this conversation as resolved.
Show resolved Hide resolved