Is there a standard for specifying a version for json schema

Question

One of our development partners have asked if there is a way we could specify an interface version within our JSON Schema definition. There isn't a "$version" key so is there a recognised "standard" that we ought to follow (I can't use $id as we are using $ref's elsewhere so the document won't validate any more). We are on Draft-6 so $comment isn't available per-se.

Validation-wise XML Spy is quite happy for me to add a "version" key to the top level, so I could just do that but if there is a more usual approach I'd rather do that.

Hospitalize

Answer 1

There is no standard way to do this defined by JSON Schema. Adding keys to the schema is allowed, as unknown keywords will be ignored by processors.

I usually advise using the $id for versioning, with semantic versioning as part of the $id value. You would have to update your references, but then you could make sure you keep semver expectations.

Often, large scale projects create release bundles, which then have a group of schemas live under a specific semver. For example Human Cell Atlas: https://schema.humancellatlas.org/a

There's also nothing to stop you from creating a new object to contain all your meta info you want to include about a schema, using a key of your choosing at the schema root level.

Dexter

Answer 2

Why does your development partner want to version the schema? I can think of a few reasons, which dictate different solutions:

1. Your partner is writing code that receives and processes JSON data. Because the API is in development and may change over time, they want to ensure that the data they are receiving is in the (only) format they expect.

   • Solving this desire does not require a version. Validating the JSON data received against the schema will show definitively if the data is in the desired format or not, in a way that is more correct and robust than comparing version strings.

2. Your partner is writing code that receives and processes JSON data, and has to support legacy data with different schema changes over time. They need to be able to detect which format a JSON data chunk is in before branching to the correct code execution.

   • Solution 1: keep n schema copies around and validate that data against each until finding one that matches, and execute the code path associated with that schema. The schema do not need to include explicit versioning—they could be differentiated by the name of the directory they are stored in (schema/1-1-0/my.schema.json) or the name of the file (schema/my.schema_1-1-0.json)—but for clarity the title and/or description fields at the root of the schema may be used.
   • Solution 2: include the version information in the JSON data as a custom property, and branch based on this string or number. The schema can then require a specific value (e.g. 1-1-0) for this property, which concurrently defines the version of the schema.

     {
        "$id"        : "http://me.com/my.schema.json",
        "$schema"    : "https://json-schema.org/draft/2020-12/schema",
        "type"       : "object",
        "required"   : ["version"],
        "properties" : {
          "version" : { "type":"string", "const":"1-1-0" },
          ...
        }
     }
     

3. When opening and looking at a JSON Schema file, the partner wants to be able to tell when it was last updated, or what "flavor" of the schema they are looking at.

   • If this is not already handled by a shared version control system, this desire can be easily accomplished via the title and/or description annotation keywords at the root of the schema.

     {
        "$id"        : "http://me.com/my.schema.json",
        "$schema"    : "https://json-schema.org/draft/2020-12/schema",
        "title"      : "Widgets for Me.com",
        "description": "Version 1-1-0; last updated 2023-07-19",
        ...
     }
     

Coe

Answer 3

Snowplow's SchemaVer semantic versioning for schemas is an option.

Stralka

I've downvoted because while this is an ~interesting means for how to compute the version (inline with semver, but sligthly different), it does not answer the question for how to specify the version within the schema definition itself. – Coe

Answer 4

Declaring a dialect ?

A version of JSON Schema is called a dialect. A dialect represents the set of keywords and semantics that can be used to evaluate a schema. Each JSON Schema release is a new dialect of JSON Schema. JSON Schema provides a way for you to declare which dialect a schema conforms to and provides ways to describe your own custom dialects.

https://json-schema.org/understanding-json-schema/reference/schema.html#declaring-a-dialect

Oarlock

I'm not an expert on this - but IIUC a dialect seems to refer to the version of "the schema machinery" itself, rather than the data content of any particular schema as it evolves over time. I think the original question is about the latter. – Scrapbook