ajv-merge-patch
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/ajv-merge-patch package

    5.0.1 • Public • Published

    ajv-merge-patch

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

    build npm version 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

    Install

    npm i ajv-merge-patch

    DownloadsWeekly Downloads

    46,942

    Version

    5.0.1

    License

    MIT

    Unpacked Size

    24.9 kB

    Total Files

    19

    Last publish

    Collaborators

    • esp