ajv-merge-patch

ajv-merge-patch

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

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:

• 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.
• $ref in both source schema and with patch take into account current $ref resolution scope (from version 2.0.0).

See also:

• v5 proposal
• $merge and $patch tests
• discussion in JSON-Schema-Org

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