Spec Update: Specify how the stable URI works

[jdesrosiers]

The stable dialect URI identifies a schema as using the latest version of the standard dialect. What schema this URI identifies depends on what the implementation supports. Generally, the implementation will associate the stable URI with the meta-schema for the latest release they support. However, implementations may use a custom meta-schema that better represents what it supports. For example, if the implementation supports all of 2024 and some of 2025, they might want to use a custom meta-schema that includes only the 2025 keywords they support.

[gregsdennis]

However, implementations may use a custom meta-schema that better represents what it supports. For example, if the implementation supports all of 2024 and some of 2025, they might want to use a custom meta-schema that includes only the 2025 keywords they support.

Are you thinking about things like VSCode which supports 2020-12 except for $dynamic* (and maybe a few other bits)?

Otherwise, I find it difficult to believe that an implementation will go to the effort (on their own) of creating their own meta-schema to list partial support instead of using the latest meta-schema in their lib and documenting that they don't support some things.

I think the solution is to make this a harder requirement:

"Implementations MUST associate the stable URI with the meta-schema for the latest release they fully support. If an implementation supports individual features from one or more subsequent releases but does not fully support those releases, the implementation MUST create a custom meta-schema to identify those additional features it supports."

This way, it's clear what the stable URI means (in the context of that implementation). If they want to also support a subset of the next release(s), they are required to create a custom meta-schema.

I think this approach will better encourage full adoption of releases.

---

I expect we'll also end up with implementations, such as VSCode in its current state, where they say they support release X except for features a/b/c but they still associate the stable URI with release X even though they don't have full support. Maybe this is where Bowtie can help?

[gregsdennis]

I think the solution is to make this a harder requirement

Basically, I feel that if we don't require something, implementations won't do it.

[jdesrosiers]

Are you thinking about things like VSCode which supports 2020-12 except for $dynamic* (and maybe a few other bits)?

Yes, that's the main thing that's for. The other reason is for implementations like mine where it's problematic to use a closed meta-schema for validating a schema. I can take the release meta-schema and remove the unevaluatedProperties constraint.

I find it difficult to believe that an implementation will go to the effort (on their own) of creating their own meta-schema to list partial support instead of using the latest meta-schema in their lib and documenting that they don't support some things.

It's fine if they do that. The whole point is that implementations gets to choose how they handle those situations that makes the most sense for their implementation.

I think the solution is to make this a harder requirement

I don't think that's a good idea. Releases are irrelevant to evaluating the schema. An implementation should evaluate a schema if it understands it. Let's say VSCode supports unevaluated* (they actually don't) but doesn't support dynamic*. We're not punishing VSCode by making users jump though custom dialect hoops in order to use unevaluated*. We're only punishing users. Allowing implementations to incrementally introduce support for a release gets features out to users sooner.

Basically, I feel that if we don't require something, implementations won't do it.

I don't understand this. We're not making anything optional. We aren't saying you don't have to support all of 2025, we're saying it's ok to release support for what you have while you work on the rest. It's 2024+, not 2025-. You still can't claim support for 2025 until you support all of it, but we're allowing features to get out to the public sooner than they would if we required implementers to finish it all before they could release anything (or make users jump through hoops).

[gregsdennis]

You still can't claim support for 2025 until you support all of it

This is what I think implementations will do anyway. They'll claim support, then document that they don't support features a/b/c.

For example, despite @Relequestual's bid to get correct messaging in the editor, VSCode still documents that it supports up through 2020-12 when it clearly does not.

The JSON support shipped with VS Code supports all draft versions from Draft 4 to JSON Schema Draft 2020-12.

They don't even list the features they don't support!

I think the only way to do this is to have what you're saying in the spec: "You can't claim support for 2025 until you support all of it"

Instead what they should claim is that they support draft 7 with a/b/c from 2019-09 and 2020-12. This is your "2024+, not 2025-."

[jdesrosiers]

This is what I think implementations will do anyway. They'll claim support, then document that they don't support features a/b/c.

You're right. Some implementations are going to do whatever they want despite what we say or what the spec says. Making the spec stricter isn't going to change the behavior of people who already have no respect for what the spec says. They're going to continue to do whatever they want regardless. I think all we achieve by making things stricter is making things harder for those who do follow the rules.

[jdesrosiers]

I remembered another reason why allowing for 2024+ was important to me. It allows implementations to add support for new keywords as soon as they enter the stabilization process rather than having to wait until there's a release. People can start using them immediately and they can get usage and be stabilized sooner.

[gregsdennis]

It allows implementations to add support for new keywords as soon as they enter the stabilization process rather than having to wait until there's a release.

Resolution here: https://github.com/orgs/json-schema-org/discussions/438

[gregsdennis]

Per https://github.com/orgs/json-schema-org/discussions/671#discussioncomment-8753266, we no longer have a single stable URI.

The meta-schema URI will work as follows:

• https://json-schema.org/<version> identifies the latest release within a specific version
• https://json-schema.org/<version>/<year> identifies a specific release

I'd still like to see some discussion particularly around the idea of dropping the URL URIs in favor of some other "unlocatable" scheme, but for now we can stick with https.

---

Action for this issue is to add these requirements to the specification, ideally by explicitly listing the version and year rather than the "template" shown above.