Update dialect and meta-schema IRI semantics for v1

[jdesrosiers]

This PR brings the semantics for dialect and meta-schema IRIs inline with what we've discussed for v1.

[gregsdennis]

We really are breaking $schema as previous specs have declared it. In 2020-12 and earlier, it would both declare a dialect and a meta-schema. With this change, it's just declaring the dialect (which I understand that we've already covered in other discussions as the direction we want to go).

My primary concern now is the word itself: "schema". It's not related to what the keyword is actually doing anymore. $schema makes sense when it's related to identifying the meta-schema, but it doesn't make sense with it's unrelated to the meta-schema. (It's identifying a dialect, which maybe has a meta-schema.)

I wonder if we keep $schema as a meta-schema identifier that functions just as it did before, but we downgrade it to an obsolete keyword and favor a new $dialect keyword to serve this purpose. We can also say that it's invalid to use both. I think this would be more intuitive. (It also aligns with our new keyword life cycle of not changing keyword meanings in favor of creating a new one that does what we want.)

[jdesrosiers]

My primary concern now is the word itself: "schema". It's not related to what the keyword is actually doing anymore. $schema makes sense when it's related to identifying the meta-schema, but it doesn't make sense with it's unrelated to the meta-schema.

Hmm, that's a good point. The naming would be a confusing historical artifact. But, changing it could be confusing as well. People are already familiar with the concept that $schema is how you declare what dialect you're using. I don't think many users associate the keyword with meta-schemas because the average user doesn't have anything to do with meta-schemas. They're used by implementations, generally not users unless they are doing something custom. To almost everyone, changing the name would feel like just a name change with no good reason.

I wonder if we keep $schema as a meta-schema identifier that functions just as it did before, but we downgrade it to an obsolete keyword and favor a new $dialect keyword to serve this purpose.

From an implementation perspective, I think it would be best to stick with $schema. I imagine that most implementations aren't going to fully drop support older drafts right away, so now they have to support different ways of declaring a dialect depending on the schema. That's complicated for users and implementers. Even though it's a bad name at this point (it could be argued that it has been long before this change), I feel like it would be best to maintain consistency with what people are already familiar with. What do you think?

[gregsdennis]

People are already familiar with the concept that $schema is how you declare what dialect you're using.

I'd say that people are familiar with the idea that $schema means "this is the $id of the schema used to validate this JSON." That's why they put it in instances.

But this usage doesn't mean that. I understand that the spec clearly defines what it means, but we should also align with expectations (like making format validate by default). Changing what this keyword means to do something that aligns less with user expectation is the wrong move in my opinion.

I think a new keyword is warranted.

[jdesrosiers]

You have a good point. $schema has never been intended for use in JSON documents, so I don't think about it that way. But, it's likely that that's how most people are familiar with it.

I still think renaming is a bad idea, but you've convinced me that not renaming is also a bad idea. I'll put some more thought into it and hope others will too and share what they think.

[jviotti]

It's identifying a dialect, which maybe has a meta-schema

Would there be any realistic case of $schema being a dialect without a meta-schema? I'm probably missing many discussions around this already for v1, but is there a use case for that? I presume we would still resolve the v1 identifiers to meta-schema ourselves too?

[jdesrosiers]

@jviotti Consider the compatibility story. One of the goals is that an implementation should be able to process a schema written for a release that it doesn't support yet if the schema doesn't include features the implementation doesn't support. I realize that's a confusing sentence, so here's an example.

Let's say 2027 added propertyDependencies and Blaze hasn't added support for 2027 additions yet. If I write a schema and don't use propertyDependencies but use "$schema": "https://json-schema.org/v1/2027", Blaze would run into several problems and would likely reject my schema. First, Blaze doesn't know that meta-schema and therefore doesn't know what dialect to evaluate the schema with. Second, it doesn't have the meta-schema and wouldn't be able to validate against it.

So, we don't want schemas coupled to meta-schemas anymore because specifying a meta-schema hinders compatibility. What really matters isn't what meta-schema the schema author had in mind when writing the schema. What matters is what the implementation evaluating the schema supports. Meta-schemas can be used internally by implementations to validate that a schema they receive is compatible with what they support. Or, the can be used by developer tooling to limit the schema in a project to a specific release's feature set. But, schemas should be able to run on any implementation that supports the keywords used in the schema regardless of what meta-schema the schema author may have used when they wrote the schema.

In the new paradigm, I would write my schema with "$schema": "http://json-schema.org/v1" indicating just the dialect and not a meta-schema. Blaze would validate it using the meta-schema it has internally that describes what it supports. It would find no issues and successfully evaluate the schema.

I presume we would still resolve the v1 identifiers to meta-schema ourselves too?

If your implementation uses meta-schema to validate the schema (not all do), I wouldn't exactly say that https://json-schema.org/v1 resolves to a meta-schema, but you may have a mapping from the v1 dialect to your meta-schema that looks a lot like URI resolution. However, that relationship is specific to your implementation. Outside of your implementation, that relationship doesn't exist.

Hopefully all that makes sense. I'm still learning how best to express these concepts. Schemas self-identifying their meta-schema is at best an anti-pattern because it reduces it's compatibility capabilities. So, removing the ability to self identify a meta-schema makes sense except that it leaves $schema with a less than ideal name even though what's left is something it's always done.