Add version identifier

[joostholslag]

I'd love the ability to specify the version of a schema.
It should identify the version of the current schema (not of the specification/meta-schema.
It should be recommended to use semantic versioning of the schema.
Similar to OpenAPI info_object.version: https://spec.openapis.org/oas/latest.html#info-object
It would help to express openEHR archetype models for clinical data in something standard like json-schema.

It could be solve by introducing a new keyword like "version" where the value is a string with recommended formatting in "x.x.x".

p.s. I'm sorry if this has been asked and answered. a search for 'version' produced many results, the first two pages were not relevant and 'semantic version' didn't produce any relevant results.

[gregsdennis]

Hey there. Thanks for the suggestion. I'm pretty sure we've received this request before, but it's really been in more of a "how do I manage my schema version?" format.

I recommend doing what we actually do with the meta-schemas: embed the version into the $id URI. This promotes schemas never changing and supports a better transition story to the new version. When you have a new version, you publish it separately with a new $id. This give the consumers of your older schema an opportunity to update to the new one.

You can still use semver in the $id if you like. With the upcoming spec release, we've settled on something like /<version-number>/<release-year>, using an integer version as a semver "major" value to indicate compatibility between releases. This allows our users to also use /<version-number> to just get the latest compatible release for the version.

I'll mark this as a proposal and leave it open to get others' opinions as well.

[awwright]

@gregsdennis has a good suggested alternative.

Your idea could be pursued as part of a generic mechanism for metadata (perhaps a variation on "$comment" that accepts a JSON-LD blob), but anything more specific than that doesn't make sense.

[idanidan29]

I like the idea of using the $id method for specifying versions, but I think we can also implement @joostholslag's idea. I've thought about it and have a suggestion that takes a slightly different direction.

Instead of adding a 'version' keyword, we could introduce a boolean like version_support: true, which would enable the $id to support special version syntax, such as latest, stable, and others. If version_support is not mentioned, it would default to false, meaning the existing $id method would continue to work.

This approach offers a more user-friendly option for version control without breaking current practices.

Example

$ref Usage:

{
  "type": "object",
  "properties": {
    "patientData": { "$ref": "https://example.com/schemas/patient-record/latest" }
  }
}

And the schema would be:

{
  "$id": "https://example.com/schemas/patient-record/1.0.0",
  "version_support": true,
  "type": "object",
  "properties": {
    "patientName": { "type": "string" },
    "patientAge": { "type": "integer" }
  }
}

I know its kinda off the main topic, but I think it takes all things into consideration, and I’d love to hear feedback