For example a simple schema might be:
{
"title": "Example",
"description": "An example",
"version": "0.0.1",
"properties": {
"things": {
"type": "array",
"required": true,
"description": "An array of things"
}
}
}
During development we discover that the descriptions are not particularly helpfull to our developers so we fix that and increment the patch number:
{
"title": "Example",
"description": "An example for use within the Zeus project",
"version": "0.0.2",
"properties": {
"things": {
"type": "array",
"required": true,
"description": "An array of items bound to the users account."
}
}
}
Soon we realise that an array was a terrible choice for things because developer X needs to do Y with them and an array is making his life difficult. So we change things to an object which will break the current test code so we flag it as a minor version bump.
{
"title": "Example",
"description": "An example for use within the Zeus project",
"version": "0.1.0",
"properties": {
"things": {
"type": "object",
"required": true,
"description": "An array of items bound to the users account."
"patternProperties": {
".": {
"type": "string"
}
}
}
}
}
With internal versioning of schemas like this it can assist with development and deployment as well as APIs that may serve multiple versions of data objects in order to support legacy or stagered development.
Posted a suggestion related to this to the Understanding JSON Schema book issue queue: https://github.com/json-schema-org/understanding-json-schema/issues/116