ajv-merge-patch v5.0.1
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 inwith
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 bothsource
schema andwith
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);