JSON Schema Extensions

[awwright]

For a while I've been promising a detailed specification that lays out how JSON Schema can ensure stability (forward compatibility when we make changes), and even some amount of backwards compatibility (how should implementations handle obsolete behavior that's since been removed from old specifications).

This is a writeup that I started last week when I got bored and only had my iPad: JSON Schema Extensions 20221024.pdf

I don't know why I called it JSON Schema Extensions because in some senses it's the opposite of that: what are the minimum of things that validators must do in order work well with changes and extensions defined at a later date?

I'm still evaluating the best way to execute changes like this. It doesn't make very many major changes, it introduces the concept of an "indeterminate" result. And it makes several suggestions that I think logically flow from this.

The major consideration is that it suggests the features that we thought were "core" features should actually be grouped differently. For example, several $ keywords, and annotations, are not required concepts for validators in order to ensure interoperability.

Please let me know thoughts about this document, especially if you have any missing use cases, questions or comments about one part or another, or how this might be actually implemented.

[jdesrosiers]

Since I've been working on defining our new process and want to have a stable release out relatively soon, so I'm reading this from the perspective of how it might effect getting a release out. I don't think there's anything here that is incompatible with the direction we've been planning for.

The first section is pretty much exactly what we've been talking about doing. I think the only significant difference is that you would like compatibility to apply retroactively to previous releases and we've been talking about it only applying to the next release and forward.

The second section amounts mostly to defining a set of required keywords and proposing some new keywords. The new keywords can be proposed through the new stabilization process. We would want to make a decision before the next release on what keywords are required. It's easy to add required keywords later, but we can't make a keyword not required later. I think there should be an separate issue dedicated to that discussion. Adding new keywords can wait for now.

We have been talking about how we should have an easy way for users to declare a keyword that is a simple value annotation without having to create a vocabulary. The @ prefix idea sounds like a candidate for solving that problem. I don't know that I'd define it exactly the way you did, but it's worth exploring this approach. We should also think about if adding a feature like this later would constitute a compatibility break. If it would, we would have to have it settled before we can do the next release or come up with another solution. I'd like to see an issue dedicated to this as well.

The third and fourth sections are mostly a re-org of the spec, which should be fine to do at any time. I think that particular discussion doesn't need to hold up the next release.

If I missed anything that doesn't seem like it's compatible with the approach we've been discussing in https://github.com/orgs/json-schema-org/discussions/234, please let me know. I think it's great that you laid out your full vision so clearly. It will be good context to link to in individual issues as we collectively decide which parts of your vision to adopt issue by issue.

[handrews]

@awwright I agree with most of the broad strokes of your Part 1. [EDIT: I'll come back later with thoughts on the other parts]

$vocabulary

I particularly agree with this:

Three, [$vocabulary] requires authors to write a meta-schema for schemas whenever an extension is
needed. And JSON Schema semantics preclude embedding meta-schemas inside schemas.
So using custom extensions require loading at least two separate schema documents into your
validator (the schema and its meta-schema).

On the one hand, the multi-document problem can easily be ensured by including the process of examining $defs for schemas with $id matching the root object's $schema in the bootstrapping process. This is part of why $defs is in the core vocabulary: it ensures that at least one location is available for reference targeting regardless of what other vocabularies are in use or are understood.

On the other hand, that does not make the meta-schema all that usable. However, since $vocabulary only takes effect from the immediate meta-schema, the local meta-schema would really only need to contain its own $schema and $id plus $vocabulary and a $ref to the shared syntax meta-schema. That would bring semantic requirements into the same document, while leaving syntax constraints as external (which they always have been, which has never been a problem).

This could be further condensed by a specific keyword to use in place of $defs-searching, if we really wanted to.

Looking at the other points you make about $vocabulary:

One, it cannot not cross $ref or sub-schema boundaries (as far as I can tell). You cannot import
vocabularies by referencing another meta-schema in your meta-schema (e.g. {“$ref”: “draft-07/schema”} is not meaningful), nor can you use it inside allOf. However, this
limitation is easily relaxed.

Yes, and we've discussed relaxing it. The main reasons we have not include:

• It would exacerbate the point above, requiring even more files to be available or fetch-able. This is the main problem.
• You could possibly end up $ref-ing a meta-schema for its syntactical constraints, but pulling in a vocabulary that you don't actually need. This is not incredibly likely and not a blocker on its own, but requires some thought in how it is presented and might, together with other difficulties, suggest an alternate approach would be better.

The big problem here is how to get to an understanding of the keywords that are present with the minimal extra effort. Currently, the system is not usable in some environments because of the multi-file requirement.

Two, it is not clear that $vocabulary applies to core keywords. A single “core” vocabulary is
assumed at runtime to “bootstrap” the core keywords including $schema and $vocabulary. It’s
possible different or better defined handling could be defined, for vocabularies to override the
behavior of core keywords, or define “super-core keywords” that configure the behavior of
other core keywords. But it seems this would require much additional complexity that should
be avoided if possible.

This will get a lot simpler if we adopt the JRI proposal, as a significant chunk of core becomes a reference to a stable external spec. And that reference would be in the JSON Schema media type spec, rather than the main document.

Of the remaining keywords, $vocabulary and $schema are about bootstrapping, and we are obviously discussing them a lot right now. And at least $schema probably ends up in the media type spec. $dynamic* are not really stable yet and even if they belong in a core vocabulary (which they might not), they are definitely not "super-core".

$schema

I'm less clear on this section.

JSON Schema is not “$schema-aware” so it’s not possible to write a schema that changes meta-schemas, that is also valid against those meta-schemas.

Is this about how to handle $schema in an embedded resource? $schema is resource-scoped rather than document-scoped, and while that's a thing that needs to be handled I'm not clear on why it's a "weakness".

It is not possible to write a schema that combines the characteristics of multiple metaschemas,
the same way that a JSON document can be described my multiple profiles.

Do you mean that $schema cannot take multiple values? Is there a need for this rather than just having a meta-schema that uses allOf to combine meta-schemas? Or is it more about symmetry with media type parameters which an have multiple values?

Meta-schemas seem to be useful to determine if the schema that you’re authoring will be
compatible with a validator. But if a meta-schema is supposed to accept schemas that the
validator supports, this means that different validators will have different meta-schemas,
each unique to the features that they support, and can be no “standard" meta-schema.

Are you talking about each implementation defining their acceptable set with a meta-schema? Why would we want to do that?

If a meta-schema describes a schema to a validator, this limits the usability of the schema to
the validators that understand the semantics of, or that can read, that meta-schema.

I don't follow this point at all, I'm afraid. $vocabulary is what indicates semantics, and yes, part of its purpose is to prevent implementations that don't understand the required vocabularies from attempting to process the schema.

[awwright]

I'll see if I can rework $schema, you're right the section isn't very focused. However, it's not terribly important and doesn't impact the rest of the document very much.

Is this about how to handle $schema in an embedded resource?

Shouldn't I be able to validate a schema through a meta-schema using an off-the-shelf validator? That's not really possible if you can "change" meta-schemas inside sub-schemas. Right?

Do you mean that $schema cannot take multiple values? Is there a need for this rather than just having a meta-schema that uses allOf to combine meta-schemas? Or is it more about symmetry with media type parameters which an have multiple values?

All of the above. No one's been begging for this of course, but there's a few things I think this simplifies.

Are you talking about each implementation defining their acceptable set with a meta-schema? Why would we want to do that?

A validator being able to express the full range of schemas it can use for validation with a meta-schema just seems self-evidently useful to me.

[handrews]

Shouldn't I be able to validate a schema through a meta-schema using an off-the-shelf validator? That's not really possible if you can "change" meta-schemas inside sub-schemas. Right?

This depends on whether you think of "a schema" in terms of resources or documents. If you think in terms of resources, then there's no expectation that a single meta-schema applies to an entire document that is composed of multiple resources.

Embedded resources are essentially inlined $refs, like the result of rendering an iframe that uses a different version of HTML from the containing HTML resource.

A validator being able to express the full range of schemas it can use for validation with a meta-schema just seems self-evidently useful to me.

Perhaps this would be more clear with an example of how you would use such a thing. I agree that it's interesting, but I would not want to see a world where people chose their meta-schemas based on one or more specific target implementations. That's the opposite of interoperability.