The JSON Schema Charter

[Relequestual]

Resolves https://github.com/json-schema-org/community/issues/274, https://github.com/json-schema-org/community/issues/349 Discussion for active development: https://github.com/json-schema-org/community/discussions/286

This PR is a draft to keep track and collate the seemingly preferable suggestions from the above discussion. Comments in the markdown file link back to specific threads in the discussion where we can continue to discuss specific aspects of those sections.

Before merging:

• [x] Remove the majority of comments
• [x] Remove "(optional)" from headings
• [x] Make sure we also have an ADR
• [x] Define all the initial TSC members
• [x] Require supermajority TSC members to review and approve of the PR
• [ ] Require OpenJS Foundation CPC approval
• [ ] Require OpenJS Foundation Board approval (per comment)

Based on Feedback:

• [x] Remove potential definition of how the OpenJS Foundation operates
• [x] Remove mention of funds
• [x] Define or remove mention of Special Interest Groups
• [x] Check use of "we" pronoun. Use proper name instead
• [x] Move list of initial TSC members
• [x] Outline kinds of discussions that can and should be made private
• [x] Replace "non-public" with "private"
• [x] Move paragraph about period of leave to membership section
• [x] Move "process" related things to another document, such as a governance.md

[tobie]

Here is also a more fundamental question: Given there is no GOVERNANCE.md, I feel some of this process was drafted for this document. Is this process what you are currently following? You don't need to add new processes to join OpenJS, and you can have a much leaner Governance.

👆 This. 👆

A tiny bit of aspirational governance (labelled as such) is fine. Anything else should just be a description of how you're currently operating and be adapted as you evolve your practice. In standards terms: opt for documenting and iterating over a de facto governance model. Don't fall into a de jure approach.

[Relequestual]

lgtm

Working on it! Still a chunk more work to do 😅. Got to migrate chunks out to another file.

[Relequestual]

I have requested re-approval for this PR. I have reviewed feedback and updated accordingly.

I moved large chunks of content from the Charter.md file to the new Governance.md file.

Approval from JSON Schema team already covered the Governance.md work so far. (I've added a note at the top that some additional work may be required before the Governance file is ratified.)

Approval from OpenJS Foundation representitives will be assumed to only cover the content found in the Charter.md file unless otherwise indicated.

If there are any serious objections to this, I'll break out the governance file into another PR, but I didn't want to loose the discussion, review, and changes, made to the governance content (which would be lost if this was to be broken into a new PR).

[Relequestual]

I made a number of changes to migrate some content back to the Charter document from the Governance document, with assistance from @Julian. I then removed the Governance document, capturing that file and all the same changes from this PR, into a new PR (https://github.com/json-schema-org/community/pull/456), to simplify and streamline this PR.

[awwright]

I have a somewhat less ambitious goal in organizing JSON Schema: I think the goal should be limited to serving as a forum for implementers, and related activities that promote interoperability, at a technical or human level. I liked the idea of having some larger organization host our activities, but this has turned out to be more broad and vague than I imagined.

Now, among the things I like: not many open specifications can say they have a comprehensive test suite and end-user documentation. (An open, standardized test suite is largely unheard of in general, they are often maintained by the author in an individual capacity).

But this is written like this a software project, and it’s not. I think language like “reliable and confident use of JSON” has no limiting principle and should be made more specific. And any implication that the proposed project has exclusive claim on publishing the specification is wrong.

My understanding was, in the beginning, we were just looking specific things like website hosting, financial management, community management, and similar things that promote the standard; and that within the scope of this, we can do things like develop the test suite. But let me share some of the ways I think this goes off track.

(1) Is a reference implementation in scope?

Personally, I don’t think there should be an “authoritative” implementation. Having a reference implementation may conflict with the goal of providing an implementor’s forum (that doesn’t favor one party over another). That said, perhaps there can be a non-official research implementation, like a command-line program, and written with emphasis on modular code over performance. Especially if the alternative is doing the same research on a “production” implementation. There could even be multiple research implementations to explore different software architectures. I don’t have a particularly strong opinion on what sort of implementation work ought to be in scope, however I’d like to see the Charter provide a clear answer to this question.

Additionally, it should distinguish between funding and hosting.

(2) Is a compliance program in scope?

Is it OK to say “This implementation meets the requirements?” Or to provide any level of endorsement to implementations, more than "listed on website" but less than “official” (like "verified", "certified")?

Again I don't have an answer to suggest, but the question will come up.

(3) Scope of specification research/development/publication/endorsement

My biggest disagreement is that there is a nuance between developing vs publishing/endorsing the JSON Schema specification. The charter lists things like “Hypermedia” and “Using JSON Schema to generate UI” but these are not areas of work as such. Labor is not spent on “Generating JSON Schema”, it is spent on “researching how to describe an isomorphic mapping of a tree-like JSON structure to a relational database” or “building tooling using a JSON Schema to project a SQL query onto a JSON document.” These are presumably both “Using JSON Schema to generate databases“ but also subtly different in scope.

The likely intent of these was to specify what the specification may cover, but this isn’t sensical either; there is a difference between “JSON Schema shall standardize…” versus “JSON Schema shall capable of such things as…” (the latter implying that the particulars of some feature is out of scope, just that there shall be at least some way to do it, but left to other parties to define.) This is why I published the Use Cases document.

And then there is the matter of development vs. publication. I think any sort of endorsement or official publication is out of scope, but: Development on the specification may be in scope. Research that provides new, useful information that can be incorporated into the specification may be in scope. Providing funding to do dedicated effort on authoring or editing could also be in scope. Hosting the specification text and annotations for implementers and end users ought to be in scope.

But being “the” publisher of the specification is not possible; the process of developing and promoting any standard must necessarily happen in the larger Internet community, with experts from other domains who can review for interoperability. And there’s a bigger problem that we do not have an exclusive license. (To host a copy? Yes. To edit? Dubious. Exclusivity? No.) I’ve spent some amount of time consulting with other people, most notably at IETF 116 Yokohama and IETF 117 San Francisco, and it would be a dead end to say “sure we want feedback from everyone, but only at our house.” There’s numerous people whose job is to provide this sort of broad review, but it has to happen where they work.

(And I will point out, these experts are in the right to associate themselves with standards organizations, who serve an important role. The OpenJS Foundation is generally home to software projects where there exist numerous functional alternatives—if you don't like Node.js, then Ruby on Rails and/or other projects can generally get your company to roughly to the same place. But if you don't like HTTP—you don't have a choice.)

Again, providing a forum for implementers would work well—but to solicit feedback from the larger standards community, we have to meet them where they are. Even standardizing JSON itself was a multi-organization effort, despite being fairly straightforward (how hard could it be to publish such a tiny subset of ECMAScript, right?).

(4) What are the specific outputs?

It’s good to split up the concerns into categories like “primary” and “secondary”, but this should be better defined to distinguish what the output “shall” be and “may” be.

Usually a charter prescribes output such as “The output of this group shall be to define an algorithm that can reduce an input to 256 bits of output, providing at least 120 bits of security” etc.

Are there any actual directives that specify what shall be produced? And what’s the consequence of not meeting these requirements?

In my personal opinion, the charter should commit the project to producing a test suite and website targeting schema authors (as opposed to implementers). In scope, but not required, would be development of software that promotes interoperability (linting, research, etc).

---

I would also expect the goal/mission to be listed first, so it comes before the direction and process that supports those goals.

I'm sorry this took me so long to get around to writing. I haven't had much of an opinion until I spent some time making comparisons to other projects, and soliciting input from others. I'm still not sure about things like a TSC; that sounds like a board of directors which is normally fine when it comes to making decisions about direction and prioritization, but it also sounds like design-by-committee which is less successful, and in open standards bodies, only meets in a very narrow capacity if at all (e.g. W3C TAG).

In general, my inclination is to clone existing efforts, and only make minor changes along the edges with the help of people who've done this sort of thing before. And this is very much unlike anything I've seen before.

[Relequestual]

@awwright Thank you for your feedback. I'm currently on leave for two weeks from now, so I won't have time to form a reply for all points until I return. I may have time to form a reply for some points. Thanks.

[gregsdennis]

@awwright

any implication that the proposed project has exclusive claim on publishing the specification is wrong

Are you saying that other entities should retain the right to publish the JSON Schema specification? This sounds wrong to me. We* are JSON Schema, and we've already decided that we're self-publishing. As such, no other entity should be able to rightfully publish a JSON Schema specification.

* "We" encompasses the proposed TSC, of which you are a member.

I understand that historically, this group has handled development of the specification and left publication to a separate body (i.e. IETF). However we are no longer associated with that organization, and the organization to which we now belong (i.e. OpenJS Foundation) doesn't have a publishing body in the same way. We are self-publishing.

Is a reference implementation in scope?

I don't think that we've planned for a reference implementation. Such things are generally created as an aid to other implementors (to view behaviors in action) and spec authors (to ensure what's specified can be achieved). However, we've opted for a test suite, as you mentioned. I think this takes the place of a reference implementation.

Is a compliance program in scope?

That's basically what Bowtie is, though it's still under development. Regarding it being in scope, no, it's not. At least not right now. I think keeping it as an independent tool for right now is best, though I wouldn't be opposed to bringing it in later.

I don't think we should be "endorsing" implementations, per se, but I have no problem providing a report on compliance based on our test suite. This is actually something that having a test suite (as opposed to a reference implementation) enables.

Scope of specification research/development/publication/endorsement

I think you make a good point about listing specific usages in the charter, and we should instead link to your usage document for the specifics in this area, like we have done for governance and other things.

But being “the” publisher of the specification is not possible

Again, I disagree with you here. You cite the need for expert review (e.g. from IETF), but to my knowledge, no such review has ever been performed on any of the documents published by JSON Schema.

Our process isn't the IETF process, and we have different avenues for acquiring the review for interoperability that you're looking for. Specifically, the community that we're building is comprised of those experts. We're relying on the people who actually use and implement JSON Schema across many domains and frameworks to provide feedback on whether or not a feature works or is useful for them. Personally, I regard this kind of feedback as higher quality than that from a panel of people who "know how to write a specification."

(We're currently in that phase right now with JSON Path, and I find the reviews that we've received lack a basic understanding of the domain.)

Again, providing a forum for implementers would work well—but to solicit feedback from the larger standards community, we have to meet them where they are.

This doesn't seem to have been the case for these well-known, highly regarded, self-published, and referenceable standards:

• OpenAPI
• AsyncAPI
• GraphQL

We're just adding ourselves to that list.

What are the specific outputs?

The primary output is the specification.

Secondary to that is the test suite, tooling such as linting (as you suggest), and documentation and other literature.

Maybe this could be stated more clearly/explicitly.

Still, the existing document form started as a template from OpenJS, an organization that we're currently in process of onboarding. It's probably a good idea for us to follow their guidance.

[benjagm]

I think we should resume the work to get this charter finished ASAP and include 2 new roles to make it easier for contributors to grow in the project and someday aspire to get involved in decision-making roles.

• Maintainer.
• Triage Team.
• Community Manager.