joi-validate-patch v0.0.4

joi-validate-patch

JoiValidatePatch is a node library which validates that operations in a JSON patch document fit within a Joi validation schema describing a document structure. Validation is performed using only the schema, independently from the document(s) to be modified.

Note: only validation of independent values can be meaningfully supported.

The primary use-case is for simple schemas covering the basics of sanity validation when accepting a JSON patch to be converted into some other form of dynamic operation where loading the documents, applying the patch, and validating the result is impractical. The typical example would be updating a mongo store or relational database

Within the limitations of the use-case, some validations are easy (can the path of the operation exist in the schema?), others are challenging (if moving content from one path to another, are the schema rules compatible?), and others still are impossible (if two paths have interdependent rules, will they still be satisfied when changing one of those paths?). JoiValidatePatch only handles the easy rules and leaves the rest up to custom solutions. It can however sidestep some complexities by simply receiving a subset of the true document schema, consisting only of the paths that are safe to independently modify and/or covered by additional validation logic elsewhere.

Basic Usage

Validating a patch document against a Joi schema:

const
    Joi = require('joi'),
    JVPatch = require('joi-validate-patch');

const schema = Joi.object().keys({
    id: Joi.string().guid().required().label('id'),
    name: Joi.string().required().label('name'),
    description: Joi.string().optional().label('description'),
    favoriteToys: Joi.array().items(Joi.string().label('toy')).default([]).label('favoriteToys'),
    meta: {
        born: Joi.date().required().label('born'),
        weight: Joi.number().positive().unit('pounds').label('weight')
    }
}).label('cat');

const patch = [
    {op: 'replace', path: '/name', value: 'Tigger'},
    {op: 'add', path: '/favoriteToys/-', value: 'laser pointer'},
];

const result = JVPatch.validate(patch, schema);

if(result.error) throw result.error;

const normalizedPatch = result.value;

API

lib.ValidationError(message, details) ⇒ ValidationError

Constructor for custom error class. Takes on the properties of a patch step passed into it, or adds an errors property aggregating sub-errors.

Params:

• string message
• object details (optional single JSON patch operation or {errors: ValidationError, ...})

Returns: ValidationError

lib.validate(patchDocs, joiSchema, options, callback) ⇒ {error: ValidationError|null, value: normalizedPatchDocs}

Main library method, performs validation against a Joi schema like Joi, but accepts a json-patch item or array rather than the actual document.

Maintains consistency with Joi.validate signature and behavior (even down to the non-async callback support).

Params:

• array patchDocs (array of objects describing JSON patch operations)
• object joiSchema
• object options
  • abortEarly (default true)
  • allowedOps (array of strings for allowed patch operation types - default all)
  • allowUnknown (default false)
  • convert (default true)
• function callback (if provided, called with error, value instead of returning an object)

Returns: {error: ValidationError|null, value: [patchOperation, ...]}