JSON Schema
Consider self publishing specifications and dropping "draft" prefix #69
Replies: 5 comments 38 replies
-
|
It's my opinion that I don't think the goal of JSON Schema should be to get to a "done" state. I think in order to remain valuable and relevant it needs to keep evolving. And that's not really compatible with the IETF process. IETF is setup to form a working group to develop a standard and then disband when it's done. What we do is a "living standard" model that is more similar to what WHATWG and EcmaScript do except we call our releases "drafts" to confuse everyone. JSON Schema already operates as a self published standard, we just need people to recognize it as such. Of course the first thing we need to do is drop the "draft" terminology. I like "release" or "dialect" as an alternative, but I think we can drop the qualifier altogether as well. The other day I saw someone refer simply to JSON Schema 2020-12. I think that's good enough. Changing this terminology doesn't prevent us from continuing to maintain our spec with xml2rfc or publishing with IETF as personal drafts, but I think doing so sends mixed messages and we're better off decoupling our release process from IETF completely. The only thing we're missing is a path to officially registering |
Beta Was this translation helpful? Give feedback.
-
|
We weren't supposed to keep indefinitely releasing drafts, hence the name draft. If your specification has to be maintained as a "living standard", that suggests to me that development is probably too centralized, and the specification should be pared down to something that better supports evolution. |
Beta Was this translation helpful? Give feedback.
-
Who says we plan to? We want to publish "releases", not drafts.
Who says it has to be? Can't it be a choice? |
Beta Was this translation helpful? Give feedback.
-
|
The main thing our industry wants is a stable non-draft version. Would it be possible to make this patch release into a non-draft version, by changing schema identifiers to "spec/2021-12" everywhere ? The marketing message would be that JSON Schema has reached a stage of maturity that can move out of draft, So, |
Beta Was this translation helpful? Give feedback.
-
|
As discussed at Open Community Working Meeting 2021-12-03: Another suggested option was to release both a patch for draft 2020-12 and a corresponding non-draft version. This patch release will go ahead as an update to /draft/2020-12/. The current work on the /draft-next/ branch, in particular the IRIs, should form the first "non-draft" release next year (2022). |
Beta Was this translation helpful? Give feedback.
-
I disagree entirely. JSON Schema is more like a programming language than it is a protocol like HTTP. Specially, it's a domain specific declarative programming language where the domain is JSON validation. How many programming languages do you know that aren't updated regularly and aren't dead or dying? Change isn't a sign of a problem, it's a sign of growth. |
Beta Was this translation helpful? Give feedback.
-
|
My opinion in slight contrast to @jdesrosiers: JSON Schema doesn't have to get to a "done" state, but it needs to get to a "stable" state, like an RFC. That is: New features can continue to evolve, but people implementing against that release should be guaranteed forward compatibility. In #119 I asked: Is there a way we can guarantee that older validators reading schemas with newer features don't report a false positive? I think if we can answer this, we can publish a stable RFC, and get our media type registration. |
Beta Was this translation helpful? Give feedback.
-
|
I've made a reply on #119 : #119 (comment) Are you strongly opposed to self publishing while we discuss #119 ? I don't think we're going to reach that resolution before our intended publishing schedule for this year. |
Beta Was this translation helpful? Give feedback.
-
There doesn't seem to be a separate discussion for this yet, so I'll throw it out here -- after having read the media-type RFCs this weekend, I'm now wondering if a more appropriate name might be "application/json-schema+json" - the "json" part being the "structured syntax suffix", and the type itself being "json-schema", rather than "schema". (likewise, the name for the instance type should be "application/json-schema-instance+json".) ref https://www.rfc-editor.org/rfc/rfc6838#section-4.2 |
Beta Was this translation helpful? Give feedback.
-
|
I don't think there's anything wrong with |
Beta Was this translation helpful? Give feedback.
-
|
How much usage does that type have so far? I've never seen it mentioned outside the json schema spec itself. If it's in widespread use, yes it would be much more awkward to change it. |
Beta Was this translation helpful? Give feedback.
-
|
It's been a standard component of all the APIs I've designed since the early days of draft-04. Every resource that is returned has a I saw someone tweet something similar just today, so I know I'm not the only one who does this, but I'm also not sure how wide spread it is. However, I have never used |
Beta Was this translation helpful? Give feedback.
-
|
Regarding self publishing, I had some thoughts I shared on an Issue regarding "living standards" and some things we should avoid. |
Beta Was this translation helpful? Give feedback.
-
|
As it stands, I'm opposed to dropping "draft", but we ought to be able to do in short order. I already wrote a short response above, but I want to elaborate a little bit, informed by the research I've been doing since then. What would a reasonable person familiar with standards processes believe the "draft" designation means? I would say "not stable": that there is no obligation for long-term support. And JSON Schema don’t have the interoperability guarantees that makes a stable specification. If implementations aren’t required to support schemas authored against the very previous draft that's only three years old, then it's not reasonable to call JSON Schema "stable". So I believe the “draft” designation is still appropriate. If I thought the spec was at a point where it could be standardized, I would have submitted a BOF a long time ago. Does this mean we have to be "done"? No. JSON Schema should have mechanisms that enable evolution. A spec can evolve and also be stable. For example, HTTP has been continuously worked on, but it's been "stable" ever since HTTP/1.0 — every implementation of HTTP since HTTP/1.0 supports HTTP/1.0. In contrast, HTTP/0.9 is "unstable" and not supported anymore. HTTP/2 is another good example. Many implementations are using $schema identifiers the same way HTTP/2 used ALPS identifiers when it was experimental (each draft was published with a different ALPS identifier, and required a different implementation). Obviously, Web browsers no longer carry around 20 different HTTP/2 engines. (To be clear, I object to this usage of $schema; it was intended to enable some amount of extensibility, but it's not a version identifier.) So, we won’t be out of “draft” status until we’ve figured out how to publish an "evolvable" specification. What does a "stable" and evolvable specification look like? At a minimum, a schema written for a stable draft should work in a validator written against a revision of that draft, guaranteed. What this means exactly depends on many details. If we only needed to support embedded usage in applications, then this would be easy. But if we also need to support usage in user-agents (APIs, Web browsers, etc.), then this is a little harder. So I'm collecting examples of use cases and requirements. If we agree that we should support a certain number of use cases and requirements, and if the spec supports all of those (including meeting the interoperability requirements), then a specification will be ready to publish. These "use cases & requirements" are somewhat popular in validation. Here's the use cases & requirements for SHACL, which validates graph data. Here's an example that covers just the case of "what if I need to deploy a change to an XML schema?" I've been talking about doing this for a little bit now. It turns out it's not as simple as listing a bunch of use cases; some use cases that appear different are actually the same thing, and there's different dimensions to categorize by (validation vs. annotation is one; embedded vs. ecosystem is another; you can go from "read annotations, completely self-contained in a single program" all the way to "validate arbitrary documents against untrusted schemas from a third party" and there's yet more dimensions relating to trust and evolution/versioning of schemas). And @handrews's work has many of useful parts to incorporate. This can inform work on developing "requirements", including interoperability requirements. I think once we can describe in technical terms what our interoperability requirements are, then the question of "what should the extension mechanism look like" will become obvious. |
Beta Was this translation helpful? Give feedback.
-
|
@Relequestual I'm busy for the next few days but hopefully I can address some of the quick points
Right, the word here is less important the concept that I'm describing. We're not looking for the word "stability" as such, we're looking for the property where "the things that are relied on by third parties will continuously function as expected".
Yes, people shouldn't avoid using JSON Schema validators in production, if those validators are stable. So if it crashed that would be bad, and if it broke during a minor or patch version increment, that would also be bad (because both would be unexpected). But there's another audience to think about: Specifications and the Internet ecosystem using JSON Schema to specify interoperability requirements. Could an RFC or a W3C Technical Report, at this point in time, define a JSON Schema in their specification? They have to know ① they can update an old reference to a newer one without changes; and ② their JSON Schema won't require changes because support for something was dropped or because validator support for an old draft is poor. (* OpenAPI references JSON Schema, but in a somewhat transparent way, if your OpenAPI doesn't use JSON Schema then what our spec says doesn't impact you; OpenAPI not relying on JSON Schema to define its own essential functionality like some IETF groups have been looking to do.) So, individual releases of validators are stable—the fact that a specification is not stable doesn't generally prevent individual implementations from providing stability guarantees. But if no nuance can be appreciated, and JSON Schema as a whole must be reduced to a "stable" or "draft" binary, well then it's a "draft".
"$schema" can help many cases, it's just not sufficient for the general case. Python could do what it did because python environments are generally well controlled. You declare your packages and write tests to make sure they work together. JSON Schema even works like this a little bit. But it sometimes works like HTML too. People shouldn't write HTTP/1.0 or HTML 3 anymore. But those servers and those documents still exist, and they're still supported.
I think it's possible to support almost all of the "pre-stable schemas" with little consideration required from validators. The code might actually become simpler, depending on how much work validators are doing to day to maintain backwards compatibility. It's true that old implementations may not behave the way an author wants when presented with a new schema that expects a post-stable validator... but this is a problem right now and adding stability requirements is only an improvement.
I'm not sure "stable" is a well-defined term, but normative references must be to other stable specifications, e.g. an RFC cannot cite an I-D. It's more about what references you can cite. And there's a few RFCs that offer design guidance, see below. Responding to @handrews
I think you have the correct understanding... there are techniques that you can use that enable evolution of a protocol or media type that you can use. It's specifically semver-type major version numbers, or elements that function like that, that poses a problem in media types. https://www.rfc-editor.org/rfc/rfc9170.html (this has many good references) Note that these overwhelmingly deal with interactive protocols, media types are even more difficult because you don't know who will be reading it. Nonetheless, version numbers still pose a problem. TLS uses version numbers but not without significant problems, and a text-based HTTP/2 was simply impossible. I'm putting together a little presentation. It has some visuals, I "plot" all of the behavior space of a specification on a 2D fractal and show how different changes to the specification causes certain changes in the plot, and it should emphasize why certain changes are backwards-incompatible, and why certain designs are better for evolution and forwards-compatibility than others. In a nutshell: Evolution is enabled when a media type or protocol leaves large regions of unallocated behavior that can be expanded into later. (For example, the set of HTTP requests containing an unknown method, Content-Type value, or unknown header). You have to have a mechanism that encourages people to not venture into these regions (usually, error). And within these regions have to "partially allocate" some regions with acceptable fallback behavior so that there's a suitable upgrade path (e.g. specify regions that are ignored, so that an old implementation without the behavior is indistinguishable from a new implementation that omits the extension). And what these regions look like doesn't matter so much as that they exist, and that they are large (actually, infinite). And this should be largely orthogonal to how you define specific extensions, which should be good news to @handrews. While it's true that JSON Schema doesn't have enough of this "unallocated behavior space", much can be reclaimed, by observing that most schemas don't have a reason to venture into this space in the first place (e.g. making up keywords doing so doesn't accomplish any task, except maybe as a comment, so we can define certain keywords whose presence must error and this will remain largely backwards compatible). We can record all of the needed behavior into a table that records which regions of behavior have been defined, and in what order (lower entries don't overwrite higher entries). And then use this table to reason about how potential extensions may be defined that has acceptable behavior even with older implementations. (I dub it the "behavior space allocation table".) If we don't like the capability that a particular table offers, we can re-order its members or decide which items to remove, and we can compute exactly what the impact is to implementations and decide if that's acceptable or not (this is where Use Cases & Requirements come in). Finally, while something like "application/schema2+json" is indeed clunky, I find codenames or random letters are less so. That is, there's one more possibility, and that's we register a media type specification in the vendor tree ( |
Beta Was this translation helpful? Give feedback.
-
Got it, thanks. Yeah, I'm not a fan of semver (or anything functionally equivalent), so I think we're aligned here. There are places where I would use semver, but none are relevant to JSON Schema.
If we must have a near-term stopgap media type solution, I would like to go this route. |
Beta Was this translation helpful? Give feedback.
-
|
This discussion has drifted quite a bit. I'm going to ignore the tangents, but we need to continue the media-type discussion somewhere.
I don't see where you've answered my question about how the IETF process would work for JSON Schema. I assume that what you presumed to be my misunderstandings was your answer, but that only confuses to issue more. I knew what you meant about additional RFCs being part of the HTTP ecosystem and assumed you expected something similar for JSON Schema. However, you also say that it's not necessary for JSON Schema extensions to be standardized in that same way. So, I guess you're saying that you expect the core to be standardized, but not (necessarily) extensions? What would be considered the stable core that's standardized and what is considered an extension? How do extensions work? Are they vocabularies, or do you see some other mechanism? How will yearly updates work? I'm not talking about pre-stable yearly updates. Even once we get to stable, we expect to add new keywords or deprecate keywords (we can't remove them once we're stable, only deprecate).
I found the example of the CTO feeling betrayed by not having the draft label unconvincing. Anyone who doesn't use
I missed the argument for why we might actually be close after all. There was certainly a lot of hand-waving and I look forward to your proposal, but I remain skeptical. If we can get to stable in the next release, the discussion about whether to use the "draft" label would be moot. |
Beta Was this translation helpful? Give feedback.
-
Sorry, I guess I'm not entirely sure what I'm supposed to be rationalizing, exactly. There's many ways that we could opt to go about an IETF submission. The essential part is we add interoperability requirements & extension points to the I-D, and there's many ways we can do that (see below). Then we submit a BOF, and if there's more than a few of us, we form a working group to publish it on a standards track.
We could do it all of the above ways. HTTP and MIME (email) headers decided to use a registry. RDF, JSON-LD, and XML namespaces are examples that use URIs/IRIs and so don't use a registry. Link relations are a hybrid, you can define a URI without permission, or register a token in the registry with a published standard (and the requirements are pretty liberal).
Some amount of core behavior must be defined, yes. I would expect validation keywords at minimum, like "type" and "properties". The absolute bare minimum is interoperability: What are the core semantics that users can expect out of all implementations, that will guarantee implementations don't misunderstand each other, now and into the future? This is currently missing because there's no requirement that $schema be understood correctly. So your old schema in a new validator, or new schema in an older validator, might not just error, it might come back wrong.
Fair enough, I made a better argument that it probably wouldn't meet the requirements to be normatively cited by other RFCs, even if there was a media type registration. It's a problem whether or not $schema is used; for an RFC to use a JSON Schema in its text, it would have to work that way indefinitely into the future and the JSON Schema specification would have to guarantee that behavior. That our compatibility requirements are neither guaranteed nor endorsed by any standards org is what makes it an "Internet-Draft". Or "draft" for short. My point with Python is, as frustrating as that upgrade was, that's consistent with what they promised (no widespread compatibility problems within a major version number). Media types don't have that sort of contingency; they're supposed to work indefinitely. |
Beta Was this translation helpful? Give feedback.
-
It's hard to accept what you're proposing when you can't articulate how you see this working. I need more than vague hand waving to see how this can work.
All they have to do is include
This is only relevant if we are part of the IETF process. The point is that we aren't really an I-D and haven't been for a long time so we aren't limited to their classifications. Unless we have good reason to be part of IETF (which I'm still far from convinced about) there's no reason to keep using this term that we know is confusing people and causing harm to adoption. |
Beta Was this translation helpful? Give feedback.
-
During our Open Community Working Meeting call on 2021-10-01 (#56), we discussed the posibility of self publishing the specifications as opposed to publishing through a standards body, and drop the "draft" prefix for our release version identifiers.
As noted in #56, this discussion was the result of the Open Discussion on the future of JSON Schema at the API Specifications Conference 2021, which was chaired by @jdesrosiers.
I had hoped to capture more of the discussion post session, but nothing as of yet (#59).
This also relates to Discussion #3 "Path to standardisation!".
Since the call, some internal discussion among the core contributors has taken place, and this should be captured here in perpetuity as Slack is ephemeral, and the discussion was private anyway.
My personal initial thoughts
Having reflected, one thing that immediately comes to mind is the logistics of new URI paths for meta schemas, publication documents (on the website), and tests.
Do we use a new path segment? “Release” or “version” or similar/different?
@karenetheridge suggested
release[-/]?YYYY-MMwhich I also agree seems to make the most sense.I also think we should refer to releases as just "JSON Schema YYYY-MM".
Beta Was this translation helpful? Give feedback.
All reactions