Skip to content

Instantly share code, notes, and snippets.

@mattyod

mattyod/json-schema-version.md

Created September 3, 2012 11:11
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mattyod/3608613 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mattyod/3608613 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. mattyod created this gist Sep 3, 2012.
    57 changes: 57 additions & 0 deletions json-schema-version.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,57 @@
    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.