Stablility without a living spec

[gregsdennis]

It seems poor form of me to simply criticize the current vision of a living specification to address stability without proposing a solution, so here's my idea.

I originally laid out 18 months ago in a discussion I raised questioning the need to continue supporting older drafts.

1. We keep publishing versioned releases, probably annually.
2. Each version has an associated lifetime, and the lifetimes of sequential releases MUST overlap so that three releases are "active" at any time. This gives diferent lag times for implementors (front edge) and users (trailing edge) who wish to update (which we recognize is optional for both parties). It also provides pressure to update.
3. Provide tooling for updating schemas between versions (alterschema!).
4. Implementations are encouraged to only support "active" releases.
5. We hold a strict policy against making breaking changes, but recognize that they are occasionally necessary. When they do occur, we are loud about it (GH discussion, socials, blog post, etc.), and we MUST announce a potential breaking change at least 6 months before the release that contains it.
6. To address the complaints of catching keyword typos, we have options:
   • disallowing unknown keywords, along with supporting x- keywords as annotations (same as what the living spec requires)
   • publishing both open and closed meta-schemas (closed optionally also still allowing x- keywords)

I think this avoids a lot of the complications that have arisen from trying to make the living spec a reality while still providing a stable ecosystem.

I would also like to focus on finishing out vocabularies/dialects as a feature (option). This will help us add features without having to compromise the stability of the main spec by providing a place to design them before they're added.

[jdesrosiers]

Each version has an associated lifetime, and the lifetimes of sequential releases MUST overlap so that three releases are "active" at any time. This gives diferent lag times for implementors (front edge) and users (trailing edge) who wish to update (which we recognize is optional for both parties). It also provides pressure to update.

I don't think this is realistic. Our releases have always had an expiration and we're always encouraging people to update. We even move implementations that only support up to draft-04 to a page on our website called "Obsolete Implementations" even if they are actively maintained. The reality is that we still hear about people stuck on releases as old as draft-03. Tooling for updating from draft-03 to draft-04 was released with draft-04 and alterschema supports updating to more modern versions. The tooling exists, but that doesn't seem to be driving adoption of newer releases.

In my experience, when someone starts a project, they choose the most recent version available and they don't update to a newer version unless they need to. We can tell implementers that they should drop support for outdated releases, but there will still be a need for implementations that support those releases and my expectation is that many won't listen because their users will demand it. We've seen examples of people picking up the maintenance of abandoned implementations rather than updating their schemas and switching to another implementation that supports newer versions.

Consider the JSON Language Server that's used in most IDEs for JSON Schema support. They're stuck on draft-07 with apparently no intention to update. We've been telling them for years that draft-07 is out-of-date. There's no reason to expect that if we tell them they need to drop support for draft-07 that they will suddenly be willing to invest in supporting recent drafts or drop support for something their uses might be relying on. I expect the response will effectively be, "F__ you, we're Microsoft, we do what we want".

Consider platforms that use JSON Schema. Amazon's API Gateway service isn't going to consider dropping support for older JSON Schema versions because that could break any of their thousands of users. There are ways to migrate people to a new version of the service and sunset the laggers, but that's not an easy task and having to do that every year isn't really an option. They're either going to stick to a version for a long period of time (currently draft-04), or they're going to find a more stable alternative to use in their service.

Your proposal is much better that the status quo, but I don't expect that getting the policy to be followed universally is realistic or a good experience for users.

[gregsdennis]

Closing this in favor of https://github.com/orgs/json-schema-org/discussions/671