Guidance around previous draft support

[gregsdennis]

Do we want to have any guidance for implementations on how to handle support for previous drafts? I think most of these fall under the purvue of implementor preference, so I wouldn't expect any of this to be found in the specification.

• When are previous drafts considered deprecated or end-of-life?
• What is the ecosystem of schemas like (e.g. how many schemas these days are still draft 4)?

I don't know about other libraries, but mine is getting a bit chunky trying to support older versions, and I only support since draft 6. There are some architectural things that I could do to help maintenance, but ideally I think I want to just stop support for older drafts at some point.

[handrews]

ideally I think I want to just stop support for older drafts at some point.

I strongly agree.

In my view there have been a few "eras" of JSON Schema, within which multiple draft support is relatively easy, but across which it is more challenging. I am hoping that the next "era" will be a long-term reliable steady state. Here's how I see it (with the bolded draft in the range being the one I'll use as shorthand for the era). Dates include time when the drafts in question were expired but not yet replaced.

• draft-00, draft-01, draft-02
  • Dec. 2009 - April 2011
  • implementation: A few, with only one (JSON Schema Lint) still active
  • usage (2016+): I've never seen these in use in the wild
  • paradigm: no $ref, id, or $schema
  • other obsolete concepts: extends, optional (boolean)
  • compatibility guidance: none
  • notes: draft-00 had a problematic typo and was replaced by draft-01 the day it was published
• draft-03
  • May 2011 – Dec. 2012
  • implementation: significant, still supported by about 7 active implementations
  • usage (2016+): IIRC one big cloud provider was still using this a few years ago, but that's about all I've seen
  • paradigm:
    • id: any URI-reference
    • $ref: replacing
    • $schema: RECOMMENDED, validators MAY use to determine behavior
  • other obsolete concepts: extends, disallow, required (boolean)
  • compatibility guidance: $schema usage intended to "prevent conflicts with future JSON Schema specification changes."
  • notes: Even our "obsolete implementations" page won't show projects that only implement up to draft-03
• draft-04, [draft-05]
  • Jan. 2013 – March 2017
  • implementation: implemented broadly, still supported by most implementations
  • _usage (2016+): possibly still the most widely used version
  • paradigm:
    • id: any URI-reference
    • $ref: replacing
    • $schema: RECOMMENDED/SHOULD, "used as a JSON Schema version identifier" (but no MUST/SHOULD/MAY on how to use)
  • compatibility guidance: none (draft-04), SHOULD implement past drafts (draft-05)
• draft-06, draft-07
  • April 2017 – Aug. 2019
  • implementation: broadly implemented, required to be shown on the regular implementations page
  • usage: fairly well-adopted, particularly draft-07, I think?
  • paradigm:
    • $id: any URI-reference
    • $ref: replacing
    • $schema: SHOULD, "used as a JSON Schema version identifier" (but no MUST/SHOULD/MAY on how to use)
  • compatibility guidance: SHOULD implement past drafts
• draft 2019-09, draft 2020-12, future?
  • Sep. 2019 – ?
  • _implementation: significant but not covering every language, expected to grow due to OAS 3.1 compatibility
  • usage: I haven't been paying enough attention recently to know, OAS 3.1 likely to drive usage as it is adopted
  • paradigm:
    • $id: MUST resolve to absolute URI (e.g. only empty fragment allowed, but discouraged)
    • $ref: delegating applicator
    • dynamic referencing: unstable/experimental
    • $schema: SHOULD (resource root), MUST NOT (other schema objects), "used as a JSON Schema feature set identifier" (but no MUST/SHOULD/MAY on how to use), absence produces undefined behavior
    • $vocabulary: special case keyword only in immediate meta-schema root, MUST be respected in determining processing rules (but lack of MUST requirement for $schema undercuts this)
    • core vocabulary: varies in one area ($recursive* in 2019-09, $dynamic* in 2020-12)
  • compatibility guidance: none
• future (according to handrews, not any sort of official plan! I expect this to be disputed)
  • paradigm:
    • $id: MUST resolve to absolute URI, MUST NOT have a fragment
    • $ref: delegating applicator
    • $dynamicRef: behaves per Proposal: Remove initial resolution step for dynamic references json-schema-spec#1140
    • $schema: SHOULD (resource root), MUST be respected when determining processing rules, in the absence of $schema behavior is implementation-defined but MUST follow a clearly documented set of processing rules with a documented meta-schema
    • $vocabulary: annotation of the schema by the meta-schema, MUST be respected when attached to a schema resource root
    • core vocabulary: guaranteed stable, allowing independent development of all other vocabularies
  • compatibility guidance: MUST support the stable core, MAY implement past drafts, drafts prior to 2020-12 NOT RECOMMENDED

---

I really think we should strongly recommend against new implementations supporting draft-04, and we should encourage cleaning up architecture by dropping support.

I doubt it makes sense to draft-06 and draft-07 at this stage, given that that's where most of the "new" schema usage is so far. But I would definitely not discourage ignoring them in new implementations.

I actually think we should discourage implementing 2019-09 in favor of 2020-12. 2019-09 had issues particularly with $recursive*, and was never broadly implemented before 2020-12 came along with its OAS 3.1 compatibility.

If I were implementing a validator today, I would support draft-07 and 2020-12, and that's all. I might support draft-06 because it's fairly trivial if you already have draft-07, but I'm not sure. I would definitely not support 2019-09 because the relatively few people who used it should move up to 2020-12 easily enough. But that's my personal take, not necessarily a recommendation for the project.

[gregsdennis]

I might support draft-06 because it's fairly trivial if you already have draft-07, but I'm not sure.

Is there anything in draft 6 that's incompatible with draft 7? I believe 7 is just an expansion on 6.

[handrews]

@gregsdennis I think it is. So I'd probably support draft-06 just because it's easy, but I couldn't remember off hand. But I'd avoid 2019-09 because no one should bother learning $recursive* and everyone should consolidate on 2020-12/OAS 3.1.

[awwright]

Do we want to have any guidance for implementations on how to handle support for previous drafts? I think most of these fall under the purvue of implementor preference, so I wouldn't expect any of this to be found in the specification.

We should. Seeing how different implementations have diverged on how to support historical behavior (i.e. backwards compatibility), we should probably add some official guidance.

When are previous drafts considered deprecated or end-of-life?

All drafts except the most recent one are end-of-life: if we wanted to require that implementations maintain support for a feature, we would have carried that feature over to the next draft.

That said, maybe we shouldn't have been so hasty to delete paragraphs from the spec. There should be a deprecation period.

What is the ecosystem of schemas like (e.g. how many schemas these days are still draft 4)?

handrews's overview is good.

I don't know about other libraries, but mine is getting a bit chunky trying to support older versions, and I only support since draft 6. There are some architectural things that I could do to help maintenance, but ideally I think I want to just stop support for older drafts at some point.

I think if we wrote some official guidance that everyone implemented in the same way, that could potentially simplify how it is implemented.

[gregsdennis]

So, I'm thinking something like how .Net (and probably others) handles its versions:

• Every version has a defined end-of-life (which usually overlaps quite a bit with at least the next version).
• There are designated LTS (long term support) releases, e.g. .Net Core 3.1 and .Net 6, and interim releases, e.g. .Net 5.
• Once a version is end-of-life, there's nothing stopping a dev from using it, but doing so comes with the knowledge that no more updates will be provided.

Managing their versions this way has the fall-on effect that when a new version releases, everyone rushes to update their code to support the new version, and often the older versions of the framework are left behind.

What this looks like for me, a JSON Schema library owner, is that when the next version of JSON Schema is released, e.g. 2023-03, I could drop 2020-12 and release a new major version (or keep the two latest versions instead of just the latest, etc.). Older schemas will still be able to be processed by using older versions of the library, but if they want to use the newer versions of the library, they'd be forced to create/update their schemas to the newer JSON Schema version.

This last bit is the exciting thing for me. Currently, there doesn't seem to be any pressure put on JSON Schema consumers to update their schemas. The perspective from implementors is, "If I support all the versions, I'll get more adoption because schemas from every version exist." And this provides zero incentive for developers (consumers of implementations) to update their schemas, which is why we still have draft 4 schemas everywhere. But if we choose to do something like the above, it would be a significant driving force for getting people to use the latest JSON Schema version and keep their schemas perpetually updated.

---

I don't think we can force implementors to do this, but if we officially state that certain versions are end-of-life and implementors no longer need to support them (SHOULD NOT might be a bit strong), maybe that would be enough to urge implementors to start to drop older versions, which would in turn urge users to update.

[gregsdennis]

Probably to help with this, there could be a draft migration tool, but it doesn't seem we know of any.

[jviotti]

What this looks like for me, a JSON Schema library owner, is that when the next version of JSON Schema is released, e.g. 2023-03, I could drop 2020-12 and release a new major version (or keep the two latest versions instead of just the latest, etc.).

This is what I feel it's the same approach. It's unrealistic for implementers of any tooling to keep support for all drafts (or a significant range of them) indefinitely. It's just too much work without a clear return of investment.

Older schemas will still be able to be processed by using older versions of the library, but if they want to use the newer versions of the library, they'd be forced to create/update their schemas to the newer JSON Schema version.

This is very aligned with my thoughts too. My plan is to keep building https://github.com/sourcemeta/alterschema to be the tool that can at least help people with that transition.

[handrews]

The LTS part is important, I think. JSON Schema's LTSs are draft-04 (because obviously, and it includes "draft-05"), draft-07 (because it was the last under the previous paradigm, and fully compatible with draft-06), and 2020-12 (because OpenAPI 3.1).

That said, LTS or not, draft-04 is past its expiration date. I merely mention it for historical context. I don't think we should consider more than two versions to be active LTS. And only that many for a transition period between them.

[gregsdennis]

@Julian this could also likely impact the test suite. If we as an org decide to deprecate older versions of the spec, it would probably make sense to tag a "completion" state for the tests of those drafts and then remove them from the git HEAD.

[Julian]

Thanks for the ping, will definitely keep an eye out here. We today have a very informal (and barely noticed) note that drafts 3 and 4 are "frozen" in the test suite. Which in practice means simply that if someone forgets to backport tests to them, I (and probably others) are lazy about doing so because it's annoying to go re-read them to see whether the behavior applies.

I'm slightly hesitant to completely delete things from HEAD honestly, rather than simply saying they're there and not really touched anymore, but I think we could likely discuss if it's important, I'm not completely against it (I just don't know that I see benefit and would rather the test suite in general not be viewed as a style guide for what to do, merely as an "apolitical" thing which represents "if for whatever reason you need to implement XYZ, here's your suite").

As an implementer I don't feel any pain personally in maintaining draft 4, I haven't needed to touch it in ages (or otherwise, the most painful is draft 2019 honestly since yeah the recursive* stuff has different behavior both from what's before it and what's after). But I support the original notion here that some joint perspective on what's useful to implement is good.

[handrews]

I'd be quite happy if we actively discouraged people from implementing 2019-09. It was hardly out long enough to get traction and 2020-12 is better by every metric ($dynamic* is still a pain but better, and there's OpenAPI 3.1 compatibility)- really, it would be best if we made an effort to discourage 2019-09. It's a high cost/low return project to implement it.

[jviotti]

@Julian

I'm slightly hesitant to completely delete things from HEAD honestly, rather than simply saying they're there and not really touched anymore

I think there is a bit of a psychological thing there. If an implementer sees the test suite maintaining directories for each version, then the implementer might be more tempted to think they should support all of them. At least that was my line-of-thought some years ago, before I knew more about JSON Schema.

I also don't think we should just delete the tests though. Maybe just moving them to a deprecated directory or something like that does the trick?

[Julian]

That's fair (both parts), I'm definitely fine to move them aside.

[Relequestual]

OK. There's some discussion on "LTS" and "deprecating" previous versions.
What could that mean practically?
What type of Long Term Support do we as JSON Schema org offer if a release is LTS?
What does "deprecated" mean for JSON Schema spec (org)?

(This discussion is on the 2022-08-01 OCWM FYI.)

[gregsdennis]

Currently, we're still adding tests into draft 4, etc. That could stop, for one. There's also talk about moving deprecated version test suites into an "archived" folder or something.

We're also already not patching the old drafts, so I don't know that any special action needs to be done there.

I think this is more about helping implementations by telling their consumers that they shouldn't expect older schema versions to be supported, which seems to be an issue.

It would also alleviate some of our cognitive load because we wouldn't have to remember nuances among 5 different schema versions.

[handrews]

@Relequestual I think I agree with what @gregsdennis and @Julian were discussing regarding the test suite. We probably need a conversation about the role of the test suite in communicating various things to the JSON Schema community. But there's no patching of past versions (nor should there be), so the only meaningful "support" from us is the test suite.

I would propose something along the lines of:

• historical: draft-04 and earlier (we strongly recommend against support due to age and due to complexity given the amount of change sense then, although of course they can be implemented for projects with historical requirements; tests are frozen but still available back to draft-03)
• superseded: draft-06, 2019-09 (each of these has a corresponding recommended release that should be the primary focus for its paradigm, so we do not recommend implementing these; tests are best-effort, meaning that anything useful for the recommended versions is backported, but features unique to these drafts won't see a lot of effort)
• recommended: draft-07, 2020-12 (we recommend all of these, and believe the oldest represents the current center-of-gravity of the community; tests are actively maintained and expanded)

These might not be the right words exactly, but I think it gives the right impression of the three categories.

A "recommended" release moves to superseded if we publish a release with significant changes but the same fundamental paradigm.

Whenever a "recommended" release moves to "historical", its related "superseded" releases move with it. We wouldn't move "superseded" to "historical" separately, because "superseded" basically means "this is pretty easy to implement if you are implementing the correlating 'recommended' draft, we just think you don't need to bother unless you want to."

Any sort of test reporting regarding conformance can show these categories as well. This would guide folks to draft-07 and/or 2020-12, which is what we want. We'll need draft-07 for quite some time given the typical implementation and support timeline. I think these three categories would give the right impression, which is otherwise challenging as, at first glance, it seems like a fairly random selection of drafts that are or are not recommended. The "superseded" category explains why certain recent drafts are less recommended than older drafts (e.g. 2019-09 vs draft-07).