JSON Patch Rules

Tools and specification for defining rules about how a json patch should be applied to an object.

Usage

npm install json-patch-rules

For some json patch object, like:

const json_patch = [
    { path: "/user/email", op: "replace", value: "[email protected]"},
    { path: "/user/friends/0/bestie", op: "replace", value: true},
    { path: "/user/role", op: "add", value: "god"}
];

Rules can be applied to verify the validity of the JSON Patch, like:

const JSONPatchRules = require('json-patch-rules');

let rules = [
    { path: "/user/email", op: "replace", value: "[^@]+@[^\.]+\..+"},
    { path: "^/user/friends/.+/bestie", op: "replace" }
];

let patch_rules = new JSONPatchRules(rules);
let valid = patch_rules.check(json_patch); //this is false, can't change user.role in a patch

Motivation

RFC 6902 defines the JSON Patch specification which allows for an object transformation by applying a set of operations. While not limited to REST APIs, a primary use case of JSON Patch is with a PATCH verb applied to an entity located at a RESTful URI.

On the client side, it is frequently necessary or desirable to perform some logic to determine whether a PATCH operation should be applied. JSON Patch has rudimentary support for this with the "test" operation, but this is limited to a simple value check at a path. This limitation is being addressed at the IETF by J.M. Snell with the JSON Predicates spec.

This repository proposes a specification and some tools for addressing the server side of the PATCH process.

The Problem

In real world PATCH scenarios, it is rare, if ever, that the server can completely trust a PATCH document sent by a client. Imagine we have a user object that looks something like:

{
    username: 'beeblez',
    email: '[email protected]',
    password_hash: '...',
    role: 'worker'
}

A patch document that looks like

[{"op":"replace", "path": "/email", "value":"[email protected]"}]

could be perfectly acceptable, allowing the user to change their email address, assuming authentication/authorization on the REST endpoint passes.

It is pretty unlikely that we'd want a user to be able to submit a PATCH that looks like this, though:

[{"op":"replace", "path": "/role", "value":"god-mode"}] //now I own everything!

This situation leaves it up to each server implementation to explicitly check patch paths and verify rules, which can be tedius. This project provides a proposed spec and a simple utility to declaratively define PATCH rules.

The Spec

A rule set is simply a JSON array of rule objects. A rule object is designed to be similar in structure to a JSON Patch operation object, and in its simplest form looks like:

{ "path": "/email", "op":"replace" }

This rule indicates that the "replace" operation is allowed on the "email" property.

Multiple operations can be specified like

[
    { "path": "/email", "op":"replace" }
    { "path": "/email", "op":"delete" }
]

or, as shorthand the "op" property can be an array:

{ "path": "/email", "op":["replace","delete"] }

a simple test can be applied with RegEx:

//make sure the value looks like an email
{ 
    "path": "/email", 
    "op":["replace"], 
    "value": "[^@]+@[^\.]+\..+"
}

if the "value" property exists and is a string, it will always be interpreted as a regular expression. Otherwise, a strict equality comparison will be used.

"from" and "path" will also be intpreted as a regular expression if the first two characters are "^/". Since all valid JSON Pointer paths begin with "/", "^/" indicates that a RegEx should be applied to match the path starting with "/".

//only allow values from the 'all_friends' array to be moved to
//the 'best_friends' array
{ 
    "from": "^/all_friends/.+", 
    "path": "^/best_friends/.+", 
    "op":"move"
}

As with JSON Patch, the "path" and "from" properties are RFC 6901 JSON Pointer paths, or a regex to match a path.

Using the "value" property with a regex allows for simple tests, which are appropriate for many situations. For more complex rules, JSON Predicate rule checks can be applied:

{
    "path": "/age",
    "op":"replace",
    "test": [
        {"op":"type", "path":"/value", "value":"number"},
        {"op":"less", "path":"/value", "value":120},
        {"op":"more", "path":"/value", "value":0},
    ]
}

"test" supports nesting and complex rules, as as explained in the RFC.

For tests can be applied widely by omitting "path" and/or "op" properties:

//this will be applied to all 'delete' patch operations
{
    "op": ["delete"],
    "test": [
        {"op":"contains", "path":"/path", "value":"inactive"},
    ]
}

//this will be applied to all operations on the 'friends' path
{
    "path": "/friends",
    "test": [
        ...
    ]
}

There are two approaches to rule specifications, fields can be whitelisted or blacklisted. This determines what action should be taken when a patch operation is applied to a path where there is no rule specified.

Since either approach is valid depending on the use scenario, the rules specification itself doesn't indicate which approach should be used. Instead, this is left as an implementation detail that should be indicated via configuration or options by the JSON Patch Rules tool.