$merge and $patch keywords for Ajv JSON-Schema validator to extend schemas
Clone or download
1
Latest commit d8c8c07 Jun 25, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
keywords Merge pull request #23 from donaldjarmstrong/master Jun 25, 2018
spec Merge pull request #23 from donaldjarmstrong/master Jun 25, 2018
.eslintrc.yml test: eslint Aug 14, 2016
.gitignore chore: remove package-lock.json Jun 25, 2018
.travis.yml test: travis ci Aug 14, 2016
LICENSE Initial commit Aug 13, 2016
README.md Update to latest fast-json-patch Mar 2, 2018
index.js feat: $merge and $patch keywords Aug 14, 2016
package.json 4.1.0 Jun 25, 2018

README.md

ajv-merge-patch

$merge and $patch keywords for Ajv JSON-Schema validator to extend JSON-schemas

Build Status npm version Code Climate Coverage Status

Problem solved

The keywords $merge and $patch allow to extend the JSON-schemas using patches in the format JSON Merge Patch (RFC 7396) or JSON Patch (RFC 6902).

Schema extension is necessary if you want to add additional properties to the recursive schema (e.g. meta-schema). Consider this example:

Original schema:

{
  "id": "mySchema.json#",
  "type": "object",
  "properties": {
    "foo": { "type": "string" },
    "bar": { "$ref": "#" }
  },
  "additionalProperties": false
}

Valid data: { foo: 'a' }, { foo: 'a', bar: { foo: 'b' } } etc.

If you want to define schema that would allow more properties, the only way to do it without $merge or $patch keywords is to copy-paste and edit the original schema.

Using $merge keyword you can create an extended schema in this way:

{
  "id": "mySchemaExtended.json#",
  "$merge": {
    "source": { "$ref": "mySchema.json#" },
    "with": {
      "properties": {
        "baz": { "type": "number" }
      }
    }
  }
}

Valid data: { foo: 'a', baz: 1 }, { foo: 'a', baz: 1, bar: { foo: 'b', baz: 2 } }, etc.

$merge is implemented as a custom macro keyword using json-merge-patch package.

The same schema extension using $patch keyword:

{
  "id": "mySchemaExtended.json#",
  "$patch": {
    "source": { "$ref": "mySchema.json#" },
    "with": [
      {
        "op": "add",
        "path": "/properties/baz",
        "value": { "type": "number" }
      }
    ]
  }
}

$patch is implemented as a custom macro keyword using fast-json-patch package.

In the majority of cases $merge format is easier to understand and to maintain. $patch can be used for extensions and changes that cannot be expressed using $merge, e.g. Adding an array value.

with property in keywords can also be a reference to a part of some schema, in which case the resolved value will be used rather than the actual object with property $ref.

Please note:

  1. In case the source schema or the patch in with keyword use $ref, they won't take into account the resolution scope for their internal $refs defined by the parent objects - they will be used as separate objects.
  2. $ref in both source schema and with patch take into account current $ref resolution scope (from version 2.0.0).

See also:

Usage with Ajv

These keywords are compatible with Ajv version >=5.1.0-beta.0.

To add these keywords to Ajv instance:

var Ajv = require('ajv');
var ajv = new Ajv();
require('ajv-merge-patch')(ajv);

Using in the browser

You can include these keywords in your code using browserify.

To include only $merge keyword:

require('ajv-merge-patch/keywords/merge')(ajv);

To include only $patch keyword:

require('ajv-merge-patch/keywords/patch')(ajv);

License

MIT