Compatibility layer to use v3 JSON Schemas with more modern tools
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
cli Add command line interface Feb 22, 2015
test Remove extra "required" Jul 29, 2015
.gitignore Initial commit Dec 20, 2013
Gruntfile.js Initial commit Dec 20, 2013 Describe known issue Jul 29, 2015
main.js Remove extra "required" Jul 29, 2015
package.json Merge pull request #3 from adius/master Jul 29, 2015

JSON Schema compatibility

JSON Schema tools are now being written for v4 of the draft, but v3 schemas still exist out in the wild.

This project intends to be a converter that updates schemas to be compatible with v4 of the spec.


This tool works "in-place" - so it actually modifies the JavaScript objects representing the schema. This is simply because it's easier than cloning the data or anything like that.

This tool should also not modify schemas that are already compatible, and can even (in some cases) handle horrible merged combinations (e.g. mixed boolean/array use of required).

Usage (Node):

Install using npm:

npm install json-schema-compatibility

Convert a schema:

var api = require('json-schema-compatibility');


Usage (browser)

This has not been thoroughly tested, but it should make the API available as a global JsonSchemaCompatibility variable.

You might need a shim to get it to work in older browsers (due to use of Array.isArray() etc), but I'd imagine any JSON Schema validator would already include/require that.

Combination with other packages

The idea is that you can take your v3 schemas, and pass them through this tool before handing them to a v4 utility. For instance, using tv4:

var oldSchema = {"type": "number", "divisibleBy": 1.5};
var v4Schema = JsonSchemaCompatibility.v4(oldSchema);

tv4.validate(data, v4Schema);

Known issues/bugs

All versions of json-schema-compatibility will produce incorrect behaviour in the following situation:

    "type": "object",
    "properties": {
        "foo": {"$ref": "#items"}
    "items": {
        "id": "#items",
        "required": true

This is because to properly update /properties/foo, it needs to resolve #items. In the general case, it can't update a schema until it's fetched every schema that's referenced, which is beyond the syntactic-only fixes that we perform right now.

If you encounter this issue, give me a shout.


The code is available as "public domain", meaning that it is completely free to use, without any restrictions at all. Read the full license here.

It's also available under an MIT license.