How to manage meta-schema updates between draft releases

[jdesrosiers]

Although we try not to change the meta-schema between draft releases, sometimes it's necessary. In the past, we've only made changes for the most critical bugs and we made those changes in place (same URI). The spec says, the following about meta-schema updates.

Updated vocabulary and meta-schema URIs MAY be published between specification drafts in order to correct errors. Implementations SHOULD consider URIs dated after this specification draft and before the next to indicate the same syntax and semantics as those listed here.

The part about assuming the syntax and semantics based on the URI is not correct because $schema is not the indicator of the version of the spec the schemas uses. It's now $vocabulary that determines semantics. In @handrews's words,

implementation behavior should be done based on vocabularies, which are currently identified by pure URIs (there's no machine-readable spec even if there is a resource located at the URI). Since there's no machine-readable file to break or have a bugfix, those URIs should not change unless the identified semantics change.

So really, behavior shouldn't switch based on the meta-schema URI anymore, that's more of a human-friendly shortcut so most schema authors don't have to think about the seven (or whatever it is) different vocabularies in use. That was part of the whole point of separating vocabulary and meta-schema: vocabulary URIs are more stable and actually determine behavior, while people should feel free to write their own meta-schemas for whatever reason, which mostly will not be specifically recognized by the implementation.

So technically, releasing a meta-schema with a new URI shouldn't be a problem for implementations, but it would be very confusing for the community. When people start seeing $schemas like https://json-schema.org/draft/2021-04/schema, it's ambiguous whether a new draft came out or a bug was fixed in the meta-schema. Even tho $schema doesn't actually identify the draft semantics, that is the primary signal users will use to determine which draft a schema adheres to when reading a schema and it should send a clear message to the user.

Proposal

Meta-schema updates should include a version identifier such as https://json-schema.org/draft/{draft}/schema/{version}. The original template https://json-schema.org/draft/{draft}/schema can be used to refer to the "latest" version for that draft. If you want updates automatically, you can use the "latest" template. If you want to pin to a specific version you can use the "version" template. Both templates clearly indicate which draft semantics are in use.

Original Discussion: json-schema-org/json-schema-spec#1089

[karenetheridge]

Meta-schema updates should include a version identifier such as https://json-schema.org/draft/{draft}/schema/{version}. The original template https://json-schema.org/draft/{draft}/schema can be used to refer to the "latest" version for that draft.

To be clear, these URIs would be used as the $id in the document itself, and referenced by other schemas (as well as itself) in the $schema keyword.

• Should we version the subschemas (the individual vocabularies, loaded via $ref) as well? .../draft/{draft}/schema/{version} would have to then reference versioned vocabulary subschemas, but .../draft/{draft}/schema can either reference unversioned vocabulary subschemas, or always be updated to point to the latest versioned documents.

• should the versioned schemas use "$schema": "...its own uri" or "$schema": "..unversioned uri"?

[jdesrosiers]

I expect versioned URIs would be used everywhere including vocabulary meta-schemas. The non-versioned URIs would not appear in any schemas. They would always just be redirects to the latest versioned schemas.

Example update to validation vocabulary:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema/2021-09-14",  // <= Update version URI
    "$id": "https://json-schema.org/draft/2020-12/schema/2021-09-14",  // <= Update version URI
    "$vocabulary": { // Vocab identifiers are always stable
        "https://json-schema.org/draft/2020-12/vocab/core": true,
        "https://json-schema.org/draft/2020-12/vocab/applicator": true,
        "https://json-schema.org/draft/2020-12/vocab/unevaluated": true,
        "https://json-schema.org/draft/2020-12/vocab/validation": true,
        "https://json-schema.org/draft/2020-12/vocab/meta-data": true,
        "https://json-schema.org/draft/2020-12/vocab/format-annotation": true,
        "https://json-schema.org/draft/2020-12/vocab/content": true
    },

    "allOf": [
        {"$ref": "/draft/2020-12/meta/core/2020-12-07"},
        {"$ref": "/draft/2020-12/meta/applicator/2020-12-07"},
        {"$ref": "/draft/2020-12/meta/unevaluated/2020-12-07"},
        {"$ref": "/draft/2020-12/meta/validation/2021-09-14"}, // <= Update version URI
        {"$ref": "/draft/2020-12/meta/meta-data/2020-12-07"},
        {"$ref": "/draft/2020-12/meta/format-annotation/2020-12-07"},
        {"$ref": "/draft/2020-12/meta/content/2020-12-07"}
    ],

    ...

{
    "$id": "https://json-schema.org/draft/2020-12/meta/validation/2021-09-14", // <= Update version URI
    "$schema": "https://json-schema.org/draft/2020-12/schema/2021-09-14", // <= Update version URI
    "$vocabulary": {
        "https://json-schema.org/draft/2020-12/vocab/validation": true
    },

    ...

{
    "$schema": "https://json-schema.org/draft/2020-12/schema", // => points to https://json-schema.org/draft/2020-12/schema/2021-09-14
    ...
}

Edit: Added day to version dates per @karenetheridge's suggestion

[karenetheridge]

        {"$ref": "meta/unevaluated/2020-12"},
        {"$ref": "meta/validation/2021-09"}, // <= Update version URI

The timestamps here are confusing -- one is a draft version, and the other is a release date. Using the release date after the draft version here as well would be a little clearer.

I would suggest using a full YYYY-MM-DD format for the release date, so it looks less like a draft version. Also it allows for the possibility of two revisions in the same month, which can certainly happen if errors are made in the first fix.

[jdesrosiers]

I agree, we should include the day in the version. I just modified the exiting meta-schema for the example, but my personal practice is to always use the full path when using relative URIs. Adopting that practice would also help with not confusing dialect dates from version dates: /draft/2020-12/meta/validation/2021-09-14.

[GabenGar]

Sounds like it's time for $version property which is a semantic version string. It conveys all needed hints to the consumer in regards to how to handle updates and and isn't bound to a timestamp (which goes through a ton of transformations while being used).

[karenetheridge]

It conveys all needed hints to the consumer in regards to how to handle updates

No it doesn't; only semver has implicit meaning and we don't use semver (nor do we want to be locked into the constraints it imposes, like when major or breaking changes can be made).

[awwright]

Encoding a version identifier into the document is generally frowned upon... Because if we had to break reverse compatibility, that's effectively just creating a new media type entirely. And ideally, the definition is always forward-compatible. So all the features that semver provides aren't relevant here.

[jviotti]

I wonder if what consumers are mostly interested in is whether a given schema is backwards-compatible, forwards-compatible or fully-compatible with respects to the previous schema. Maybe that aspect can be encoded into some sort of JSON Schema custom versioning strategy? Having that information embedded into the versioning would greatly simplify many schema evolution use cases.