mattyod/json-schema-version.md

## json-schema-version.md

      
    Raw
  

              json-schema-version.md
            
          
    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.