Dialect URIs for stable spec

[jdesrosiers]

I think we've come the agreement that we will have snapshot meta-schemas for each release with unique identifiers but also have a stable URI that represents the latest version the consuming implementation supports. Let's decide what those URIs are going to be.

Here are some suggestions

Stable URI

• https://json-schema.org
• https://json-schema.org/schema
• https://json-schema.org/validation
• https://json-schema.org/standard

Release URIs

• https://json-schema.org/2024
• https://json-shcema.org/schema/2024
• https://json-schema.org/validation/2024
• https://json-shcema.org/2024/schema
• https://json-schema.org/2024/validation
• https://json-shcema.org/release/2024/schema
• https://json-schema.org/release/2024/validation

[jdesrosiers]

Stable URI

• https://json-schema.org
  This is nice in that it's as simple as possible for users. It could be confusing to some that if you follow it without the proper Accept headers you get our website. Also, with our current website solution using Github Pages, we wouldn't be able to support that content negotiation.
• https://json-schema.org/schema
  There used to be a stable URI like this but with http rather than https that effectively represented draft-04. We know that some implementations support https for older dialect URIs, which means that using this URI could cause problems for some. Therefore, I recommend not using this URI.
• https://json-schema.org/validation
  This is my favorite. This is the dialect described by the validation spec, so I think using "validation" makes a lot of sense. If we introduce other specs for other domains the pattern could be used there as well (/codegen, /formgen, /database, etc.)

Release URIs

This is just a matter of preference I think. None have any issues I can think of. I prefer https://json-schema.org/validation/{year}.

[jdesrosiers]

It seems we're still thinking about this a little differently. I think of the stable dialect URI as really just an identifier. It's purely a convenient redirect for users and only has meaning in the context of an implementation. So, the living meta-schema using that $id feels confusing because there's no implementation involved. I was imagining the living meta-schema just using the release URI for the next release or something unique like /living.

The living meta-schema should definitely be available on Github. If we use the stable dialect URI, I'm ok with that, but I find it a bit confusing. I strongly think we shouldn't host it at the stable dialect URI, but I'd be ok with linking to it's Github location from the website.

[Relequestual]

Also, with our current website solution using Github Pages, we wouldn't be able to support that content negotiation.

An aside, using Cloudflare would allow us work around this by having silent redirects based on headers.

[Relequestual]

I'm in favour of number 3 here.

There is another question... would this mean we stop serving /schema?

[gregsdennis]

@jdesrosiers and I both thought that we had stopped serving that some time ago. I remember having the discussion about it. Maybe we decided it would break too many people. One possible approach would be to move it to a permalink for draft 2020-12 and serve a 301 redirect from it. Of course, we'll need to advertize that we're doing this, and what the correct URIs are for the stable meta-schemas.

[jdesrosiers]

Maybe we decided it would break too many people.

I don't think there was a reason to leave it. I suspect that the only reason it's still there is because no one has taken the initiative to remove it.

One possible approach would be to move it to a permalink for draft 2020-12 and serve a 301 redirect from it.

I think it hasn't been a thing plenty long enough that we can simply remove it a this point. It's also always been the case that no one should be relying on us hosting any meta-schemas. That's never what they were there for. If removing it breaks someone, that's their fault for relying one something that they never should have been relying on in the first place.

we'll need to advertize that we're doing this, and what the correct URIs are for the stable meta-schemas.

Simply telling people it's going away won't work. If we want to be nicer about this than we need to be, I'd suggest we intermittently stop hosting it. Applications that will be affected will notice the interruption and have to take action to avoid the next blackout. When people stop complaining that it disappeared, we'll know we can remove it for good.

[gregsdennis]

Another aspect to consider is strictness of the meta-schema. I believe we landed on supplying both open and closed versions of the meta-schema as they're both useful for different scenarios.

Because of this, I think it's beneficial to consider this in the URI discussion.

I think for these, we have the primary be open and add /strict to the path for the closed version. This would give us https://json-schema.org/validation/strict for the stable URI, and I think the https://json-schema.org/2024/validation/strict pattern works best for releases.

[jdesrosiers]

I'm not sure we came up with a reason for a release specific meta-schema to not be strict. And as long as the schema the stable URI points to can be customized to reflect the needs of an implementation, we probably don't need a separate URI for an open/closed for the stable URI either. It's just up to implementations to use what makes sense for them.

Assuming we do need it ...

My only concern about appending /strict is that we expect that the most common and expected use will be "strict" since we are now disallowing unknown keywords. It's probably best if "strict" is the default.

I'm not sure if there would be any technical problems with this, but it would be nice if we could express this difference with fragments (#strict or #open) rather an path segments (/strict or /open). That would allow us to have one meta-schema capable of describing both.

[gregsdennis]

I'm not sure we came up with a reason for a release specific meta-schema to not be strict.

Sure.

And as long as the schema the stable URI points to can be customized to reflect the needs of an implementation, we probably don't need a separate URI for an open/closed for the stable URI either. It's just up to implementations to use what makes sense for them.

I don't like the idea of implementations customizing the meta-schema and packaging that under the stable URI. It should match what we publish under the stable URI when the implementation package is released.

Also, people have repeatedly asked for a strict meta-schema. If we follow your below suggestion, making strict/closed the default, then people are going to be asking for an open one that they can extend. I think it's worth having both.

I'm not sure if there would be any technical problems with this, but it would be nice if we could express this difference with fragments (#strict or #open) rather an path segments (/strict or /open). That would allow us to have one meta-schema capable of describing both.

{
  "$schema": "https://json-schema.org/validation",
  "$defs": {
    "open": {
      "$anchor": "#open",
      // define all of the schema stuff in here
    },
    // more definitions
  },
  "$ref": "#/$defs/open",
  "unevaluatedProperties": false
}

I think that would do it. Feels a bit weird to have the primary schema in a definition, though. Also, this seems to be making a bad example or setting a precedent of "this is how to write schemas," which is likely not something we want.

[jdesrosiers]

I don't like the idea of implementations customizing the meta-schema and packaging that under the stable URI. It should match what we publish under the stable URI when the implementation package is released.

I'll start another discussion where we can dig into this topic (but likely not til next week).

[jdesrosiers]

Spin-off discussion at https://github.com/orgs/json-schema-org/discussions/438

[SorinGFS]

I think you should also consider using querystrings and urlRewrite in webserver config. E.g.,

for the latest
https://json-schema.org/

for specific need
https://json-schema.org/?v=2024&meta=validator

[jdesrosiers]

That's reasonable, but I'm not sure we can host files with query parameters with our current website stack (Github Pages).

[SorinGFS]

This would give a ton of flexibility, and I think if you come to the conclusion that this is better, then you should not let the webserver to stay in your way.

[jdesrosiers]

I think if you come to the conclusion that this is better, then you should not let the webserver to stay in your way.

Agreed. I just mention it so people are aware that there will is an additional problem we will need to solve if we choose that option. If we really want to use URIs that don't work with our web stack, I'm sure we can find a way.

[jdesrosiers]

I'm going to go ahead and propose a resolution. I propose we use https://json-schema.org as the stable dialect URI (which doesn't need hosting) and https://json-schema.org/{year} for release snapshots (which we would host on the website). I think the simpler we make it for users the better.

[gregsdennis]

I'm fine with this. Do we need to resolve the question about the open/closed versions? Would my proposal be acceptable, making the closed the default and the open URI be https://json-schema.org#open?

Do we need a trailing slash, e.g. https://json-schema.org/ (and https://json-schema.org/#open)?

[jdesrosiers]

Do we need to resolve the question about the open/closed versions?

I'm not sure we need it. Given where we landed on all that discussion, being able to use the stable dialect URI as whatever I need to internally addressed my need for an open schema. I couldn't think of any other use-case for it other than making it a little easier to construct dialect. I don't need it and I was the only one who was advocating for it, so maybe it's not necessary?

If we do need it, then yes, I'd go with closed-by-default and #open is a good anchor name.

Do we need a trailing slash

A path is allowed to be empty even with a fragment in RFC 3986 which is what JSON Schema uses. (It's possible that WHATWG URLs are defined differently, but that shouldn't affect us.)

[gregsdennis]

What started out as a joke to @jdesrosiers in DMs seems to have yielded a set of other options.

There's a lot of confusion around whether the schemas identified by a URI that is also a URL should be available at that URL. Historically, JSON Schema has held that, no, these are just identifiers and implementations should not expect a document to be located at the associated network location.

To alleviate this confusion, it makes sense to stop using URIs that look like network locations. That gives us:

1. URNs, e.g.urn:schema:meta
2. URLs with a custom scheme, e.g. schema://json-schema.org

I really like (2). It simple and pretty close to what we have (easily translatable), and it's fairly clear that it's not a network resource to be fetched.

Jason also pointed out that it's important to consider that while implementations aren't expected to access network locations, they are expected to have some sort of internal schema store. The URIs we use do, in a way, locate a schema within that store, so the location semantics are somewhat important. This consideration rules out URNs since they convey no location semantics.

[gregsdennis]

The point I've been trying to get across is that associating a URI with a resource is location. They're the same thing.

They're not the same thing. It's just an association; it's just a map. "Hey Implementation, when you see this URI 🏷️, use this resource 🎁." There's no location semantics in that. The user/application/whatever, external to the implementation, has already performed any locating of the resource and is merely providing it to the implementation.

I agree that it's important for the user/application/whatever to honor URI location semantics, but that's not the implementation's responsibility. The implementation's responsibility, as a representative of the spec, ends at making the association.

[gregsdennis]

... also, for $id, "Hey Implementation, I'm a schema 🎁 claiming the URI 🏷️. Use me when you see it."

[jdesrosiers]

"Hey Implementation, when you see this URI 🏷️, use this resource 🎁." There's no location semantics in that.

I honestly don't see how you can separate that from location. That sounds like instructions on how to locate a resource given a URI. You're argument is still dependent on location being a distinct concept specific to external resources.

I think at this point we've identified what's blocking us from making progress in this discussion. This concept is the crux of the discussion and I don't see a path where we're going to agree. So, I propose we bring this tangent to a close and continue with the original discussion assuming no changes to the spec. I wasn't hopeful this would go anywhere anyway. As I said, given the way the spec is now, I don't think using schema: for the stable dialect URI will be the best user experience for our community. My previous recommendation remains my preference for URIs.

[gregsdennis]

I honestly don't see how you can separate that from location.

I honestly don't see how you can precompile a schema. But like precompiling schemas, locating resources is an implementation detail.

I can separate location from association because the spec doesn't explicitly say anything about locating resources. It only says to associate a resource to a URI, whether that URI is defined by the application/user or by $id.

If I give you a schema in a box and tell you its name (or it tells you its name), yeah, you have to do something with that schema so that you can produce it later, but the spec is non-prescriptive about what should be done, which leaves different implementations open to do different things. An implementation could keep it in memory or save it to a local file or put it in a database or post it to a server. An implementation is free to do any of these and more.

If a drawing specification says that you need a square for a particular task, it doesn't care how you get the square. You can draw it. You can generate it. You can outsource it to someone on Fiverr. Whatever. Just get the square by whatever means you have. The spec only cares that you can produce a square when it asks for one. Similarly, our spec only cares that an implementation can produce a resource, not how.

Your concern is that the implementation should respect the semantics of the URI. I agree with that. But respecting those semantics is unrelated to evaluating a schema, which is the spec's concern. The only thing required to evaluate a schema is the ability to produce a resource when given a URI. That is the minimum requirement.

How an implementation produces the resource is separate from the ability to do it.

Defining what it means to locate a schema: URI resource is necessary, and odds are that many implementations will need to understand this, but it has no impact on the spec.

My previous recommendation remains my preference for URIs.

That recommendation is in active opposition to the position you've been arguing as https://json-schema.org/ returns an HTML document, not a schema.

I propose that we (all of):

1. use https://json-schema.org/{year} (or similar) for the release meta-schema URIs, and make them available at those addresses.
2. use schema://json-schema.org (or similar) for the stable meta-schema URI
3. register schema: with IANA and define it to convey "internal to the application/implementation" / "not a network/file location" semantics

All of this can be done without changing the spec, and it aligns with what you've been arguing (except the $id thing, which I still don't get, but we can continue that in DMs). If you want, we can re-evaluate the wording of this advice from Core 8.2.1 and other text like it:

In the case of a network-addressable URL, a schema need not be downloadable from its canonical URI.

I agree that doing (2) without doing (3) would send incorrect messaging (which is basically the status quo). But I disagree that the spec is implying any kind of requirement around locating resources.

[gregsdennis]

For reference, IANA URI scheme registry.

Example (icon:) of what we'll likely need to do.

[gregsdennis]

Okay... now that #460 is resolved, I think we can pick this discussion up again.

The resolution was adding an explicit allowance that file/network access is permitted but SHOULD be disabled. This explicitly gives implementations that need to have it permission to do so, which is a bit stronger than the implicit permission that was present before.

We also determined (in the discussion) that we should exemplify using non-locatable URIs for non-locatable resources. It's not a hard requirement, but if we pave the way, maybe others will follow our lead.

To that end, since the stable meta-schema isn't going to be a published document, we need to define a non-locatable URI for it. I had proposed creating a new schema: scheme for this purpose. As such, my proposal is still:

1. use https://json-schema.org/{year} (or similar) for the release meta-schema URIs, and make them available at those addresses.
2. use schema://json-schema.org (or similar) for the stable meta-schema URI
3. register schema: with IANA and define it to convey "internal to the application/implementation" / "not a network/file location" semantics

[jdesrosiers]

The result of all that discussion was for us to double down on the spec encouraging arbitrary association of URIs to schemas and discouraging scheme-based retrieval. I think introducing a schema: scheme isn't consistent with that decision. Arbitrary association makes schemes meaningless. We expect users to be using arbitrary association except in fringe applications like hyper-schema. Telling those same users that they should use schemes that don't imply location semantics doesn't make sense. It just makes things more complicated for users because we're asking them to understand details about URIs that don't affect how they use and interact with JSON Schema. If we could at least put scheme-based retrieval on equal footing with arbitrary association, I think using schema: could make sense, but I couldn't get enough support to do that. That said, I'm not that strongly opposed to using schema:. My implementation uses scheme-base retrieval, so it make sense for me. I just don't think it's consistent with how we expect users to use and interact with JSON Schema. If everyone wants to go down that route, I won't stand in the way, but I'm not supporting it either.

If we use a schema: scheme, I suggest that it not include an authority part (//json-schema.org). I'd make it a simple path like Java's classpath: scheme. Some suggestions:

• schema:org/json-schema
• schema:org/json-schema/validation
• schema:json-schema/validation
• schema:json-schema