The JSON Schema Charter

[Relequestual]

Resolves #274, #349
Discussion for active development: #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:

• Remove the majority of comments
• Remove "(optional)" from headings
• Make sure we also have an ADR
• Define all the initial TSC members
• 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:

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

[ovflowd]

Approving as OpenJS Foundation (CPC) member

Excited to see this happening :)

[mcollina]

lgtm

[karenetheridge]

JSON Schema aims to enable the confident and reliable use of the JSON data format.

I would change this to "reliable use of data expressed in the JSON format, other formats compatible with the JSON document model". JSON Schema isn't about the JSON data format itself, but about describing data expressed with that format, as well as others.

[Relequestual]

While initially thinking about this, I thought I agreed, however on reflection, I'm not sure I do. It's not in scope of JSON Schema to care about other languages which "compile" to JSON, such as YAML.

JSON Schema isn't about the JSON data format itself, but about describing data expressed with that format, as well as others.

I think this is only partially true. JSON Schema can only cater to a subset of YAML for example. It's possible to roundtrip from JSON to YAML to JSON, but not always possible to roundtrip from YAML to JSON to YAML.

The use of "JSON data format" was used in effort to convey the "in memory" materilization of the data, as opposed to just a JSON file.

I agree that "eliable use of data expressed in the JSON format" may make this clearer, however I'm not convinced about "other formats compatible with the JSON document model". "compatible" in what way?

Do you have any additional thoughts on this?

[karenetheridge]

Interoperability of what? I think this means "expressing things about the data in an interoperable way"? so some extra words could be used here to be more clear.

[gregsdennis]

I think the interoperability here is across systems, platforms, and languages.

[Relequestual]

I think wanted to leave this pretty broad deliberately. @karenetheridge is there anything related to interoperability you think shoudln't be considered in scope specifically?

[karenetheridge]

Likewise.. extensibility of what? Perhaps the use of a json schema document to fulfill other usecases that are not predicted by the specification or their authors?

[Relequestual]

In terms of "interoperability" and "extensibility", as with the other items found under "in scope", I didn't feel it needed to specify "in relation to JSON Schema" as the context.

"Documentation" as an item in the list for example, shouldn't need to say "... of JSON Schema". Same for "Critical tooling".

These are vague on purpose to avoid us having to broaden them later if we were too limiting, as we then have to go through a charter change process and get multiple approvals.

[karenetheridge]

Perhaps "test suite to be used to verify implementation conformance to the specification"

[Relequestual]

There is a lot detail that could be added to all of these items. This is supposed to be really high level. What do you feel we would gain from being more specific here?

[karenetheridge]

I'd also add "Format registry" - since OpenAPI has one, and it really should be part of the JSON Schema project for more compatibility.

[Relequestual]

What value have you seen come from the OpenAPI format registry?

[karenetheridge]

It provides a reference for applications so they can provide a consistent implementation of formats -- which is why we have specifications.

[gregsdennis]

It should be noted (and I imagine Karen is aware from the OpenAPI side of things) that were looking at importing the format registry from OpenAPI.

[karenetheridge]

Any restrictions on the maximum percentage of Governing Body members that can be employed by the same company? The risk of one company exerting undue influence over the direction of the project is real.

[gregsdennis]

We looked at this before, I but I don't remember (or necessarily agree with) why it was removed.

[Relequestual]

This clause was seen more as a governance concern than a charter related concern, and was moved out to #456, specifically this line. (This also allows us to update it without having to go back to the OpenJS Foundation for their approval.)

The risk of one company exerting undue influence over the direction of the project is real.

I hear you. Regardless of what anyone in such a position reports, such as no to little influence, that doesn't mean things can't change, or it shouldn't be a concern.

We are trying to start addressing this by engaging more with implementers: #412 - Comments and suggestions welcome.

Additionally, we are looking to encourage users to self report: #441

Further, there are plans to create a stakeholders group: https://github.com/orgs/json-schema-org/projects/12/views/5 (Although these are a little vague currently).

Open to thoughts, suggestions, comments, on all of this and anything else that comes to mind as to how we can expand our TSC. @karenetheridge your voice carries weight here =]

[karenetheridge]

Are there any such requirements today that we should be making a note of?

[Relequestual]

This is in reference to the requirement to use a CLA or DCO, and the IP policy: https://ip-policy.openjsf.org

I may be looking to seek an exemption for CLA/DCO, but that remains to be seen.

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