What exactly does the stable URI represent?

[jdesrosiers]

In previous discussion, I though we had agreed on what the stable dialect URI would represent. My understanding was that there was agreement on what I describe here, but it seems there's still some disagreement, so let's try again.

Please read the linked comments, but discuss here.

[jdesrosiers]

IMO, allowing for the stable URI to point to an implementation-specific meta-schema rather than being limited to official released meta-schemas is critical to the processes we've been discussing for the staged introduction of new keywords. New keywords can only reach "stable" status if they are used. The sooner those keywords can be made available to users, the sooner they can reach "stable" status, which is good for everyone.

What I have in mind is similar to how JavaScript evolves. Implementations start adding support for new features as soon as they're proposed and people start using them as soon as their implemented. There's no lag between spec release and implementations supporting the feature because they already support the feature. In fact, the implementations supporting the feature was a prerequisite for making it into the spec release.

I should be able to make a keyword available as soon as it's proposed and not have to wait as much as a year or more before a new meta-schema is released so people can start using it. I should be able to update my implementation specific meta-schema to include the new keyword without having to wait for the official yearly release. An alternative to this problem is for us to make a living meta-schema available to implementers that includes proposed keywords as soon as they're proposed, but that has some problems I won't go into right now unless someone asks to hear more.

A second problem with limiting to release meta-schemas is accounting for the unique needs of some implementations. For example, I need an open meta-schema for validating schemas. Validating schemas is optional, so I can't rely on unevaluatedProperties to check if a keyword is supported or not. Therefore, I explicitly check each keyword that is encountered for support and provide a much nicer error message that I can get with unevaluatedProperties. I want users to always get the nice message from the additional check rather than sometimes get a different unealuatedProperties error.

In order to get that behavior, I would have to alter the official meta-schema to remove the unevalutedProperties to get the best experience for my users. If the spec forbids such alterations, I'm going to do it anyway because it's good for my users and doesn't hurt anything. No one would even know the difference unless they read my code. The outcomes are always the same even tho I'm technically violating the spec.

I think there are some constraints we can and should put on what can be in an implementation-specific meta-schema that the stable URI is allowed to point to, but limiting to the release meta-schemas is too restrictive. An implementation-specific meta-schema must be compatible with a release meta-schema with the exception of unevaluatedProperties. That means you can add keywords, but you can't remove or modify keywords or modify $vocabularies. I think that's reasonable, but like in the previous example, this restriction is completely unenforceable and implementations are going to ignore it if it suits their needs.

[jdesrosiers]

Yes! Now we're really getting on the same page. The spec just needs to define that the stable dialect URI represents the most recent version of JSON Schema the implementation supports, potentially including accepted proposals not yet in the spec. We don't need to limit what meta-schema an implementation associates with that URI (if any). It's up to the implementation to use whatever is necessary to operate as is expected when the stable dialect URI is used.

[gregsdennis]

Does this mean you're on board with a living meta-schema as well? It would stay in sync with the spec and be updated as proposals reach stage 1. Moreover, the changes to the meta-schema would be part of stage 1 requirements.

This assumes that the implementor retains the right to maintain an internal version of the meta-schema that is only modified for proposals in order to allow the implementor to update support for those proposals as they can. Stable features MUST be included as they are in the official meta-schema.

(This is going to be fun to enforce.)

[jdesrosiers]

Yes. 💯 to all of that.

[Relequestual]

I think I agree with all of the above discussion, however something occured to me.

If an implementation modifies the meta-schema, and reports an error based on the modified meta-schema...

1. What base URI will it report? The official one, that they used, or a custom one the implementation defined?
2. How will a user understand a URI path into the meta-schema which seems to not exist in the officially published meta-schema?

Expanding on 2, sure, you could argue that the user should know they are using experimental non-stable features, but I can also imagine that someone leaves and someone else has to pick up a bunch of schemas without much of a clue, tries to modify the schema, and gets an error they don't understand how to digest, because they can't find the URI path of the meta-schema.

Thoughts?

[gregsdennis]

First, remember that this is meta-schema evaluation, which doesn't really happen a lot as it's optional. The primary cases for validating with the meta-schema is when you're authoring a schema. (And then, it's likely the editor that's using it, not the author directly.)

1. The URI will still be the stable URI. Stable features will still be well-defined. The proposals that the implementation supports will need to be documented.
2. Per this thread, we're looking at not hosting the stable URI meta-schema, so it's not "officially published." The meta-schema is live, includes all current proposals, and is available on GitHub, but it's not published.
   2+. I would hope that a dev picking up work would go to the implementation's documentation. It would probably be a good idea for us to publish documentation about expectations for support of proposals and other unstable features that's not specific to any implementation.