Section on managing schema versions?

[naught101]

I'm currently trying to come up with a solid way to manage schema versions, and to manage migrations/upgrades of objects matching those schemas. I started a discussion at https://github.com/json-schema-org/json-schema-spec/issues/19 , but it should more properly be discussed here, I think, so copying the contents over:

---

I wonder if it might be worth addressing a "recommended versioning/upgrade pathway methodology" or similar in the book.

I'm trying to implement something like this in a private project, and thinking of using something along the lines of:

• A single repository of schemas and upgrade code that can be used stand-alone or as a library in multiple languages
• Schema versions for each object type in subdirectories named after the version.
• A current_version file that keeps track of the current stable version of the schema for each object type.
• A previousVersion tag in each version of the schema (e.g. v1.1.0 might have previousVersion: 1.0.7)
• A requirement in each schema that all objects have a schemaVersion property.
• Upgrade function for each version change that can be imported into my apps, with a wrapper script for stand alone operation, in each language I care about (e.g. upgrade_v1.1.0_from_v.1.0.7.py, upgrade_v1.1.0_from_v.1.0.7.js), which handle the upgrade, and which can be chained (with pre-and post-validation).
• Some master scripts which detect the current stable schema version, object schema version, and get and run the upgrade function chain.

This feels like a sensible idea, because it keeps all of the validation and upgrade logic in the same place, and allows each part to be used as-needed in each app (in particular we have a large object store that will have objects with various different versions that need upgrading as they are accessed and used by other apps in the system).

I thought I'd chuck this up here because it might be useful as a basis for a more sensible methodology recommendation, and for the possibility that I might get some feedback on it :)

[teja-v1]

Do we have any update on this?

[cpersico]

I also think it would be useful to have a version field

[koppor]

Regarding the aspect "which version number to assign to a JSON schema", a stackoverflow question pointed me to SchemaVer. In short, it recommends following:

Given a version number MODEL-REVISION-ADDITION, increment the:

• MODEL when you make a breaking schema change which will prevent interaction with any historical data
• REVISION when you make a schema change which may prevent interaction with some historical data
• ADDITION when you make a schema change that is compatible with all historical data

[KrzysztofMadejski]

I was not convinced by SchemaVer. They themselves say that the line between model and revision is blurry. I prefer to use semver with following interpretation:

• major: breaking changes, old data can't be read using new schema
• minor: non-breaking changes, ie. adding a new field, extending a type, old data can be read using new schema
• patch: documentation updates

[KrzysztofMadejski]

What I'm wondering is how to document historical versions inside schema. Description with \n is an option, but I'd prefer some solution that formats nicer natively.