ajv-errors

Custom error messages in JSON-Schema for Ajv validator

# Contents

- Install
- Usage
  - Single message
  - Messages for keywords
  - Messages for properties and items
  - Default message
- Templates
- Options
- License

# Install

npm install ajv-errors

# Usage

Add the keyword `errorMessages` to Ajv instance:

var Ajv = require('ajv');
var ajv = new Ajv({allErrors: true, jsonPointers: true});
// Ajv options allErrors and jsonPointers are required
require('ajv-errors')(ajv /*, {singleError: true} */);

See Options below.

## Single message

Replace all errors in the current schema and subschemas with a single message:

var schema = {
type: 'object',
required: ['foo'],
properties: {
foo: { type: 'integer' }
},
additionalProperties: false,
errorMessage: 'should be an object with an integer property foo only'
};
var validate = ajv.compile(schema);
console.log(validate({foo: 'a', bar: 2})); // false
console.log(validate.errors); // processed errors

Processed errors:

[
{
keyword: 'errorMessage',
message: 'should be an object with an integer property foo only',
// ...
params: {
errors: [
{ keyword: 'additionalProperties', dataPath: '' /* , ... */ },
{ keyword: 'type', dataPath: '.foo' /* , ... */ }
]
}
}
]

## Messages for keywords

Replace errors for certain keywords in the current schema only:

var schema = {
type: 'object',
required: ['foo'],
properties: {
foo: { type: 'integer' }
},
additionalProperties: false,
errorMessage: {
type: 'should be an object', // will not replace internal "type" error for the property "foo"
required: 'should have property foo',
additionalProperties: 'should not have properties other than foo'
}
};
var validate = ajv.compile(schema);
console.log(validate({foo: 'a', bar: 2})); // false
console.log(validate.errors); // processed errors

Processed errors:

[
{
// original error
keyword: type,
dataPath: '/foo',
// ...
message: 'should be integer'
},
{
// generated error
keyword: 'errorMessage',
message: 'should not have properties other than foo',
// ...
params: {
errors: [
{ keyword: 'additionalProperties' /* , ... */ }
]
},
}
]

For keywords "required" and "dependencies" it is possible to specify different messages for different properties:

var schema = {
type: 'object',
required: ['foo', 'bar'],
properties: {
foo: { type: 'integer' },
bar: { type: 'string' }
},
errorMessage: {
type: 'should be an object', // will not replace internal "type" error for the property "foo"
required: {
foo: 'should have an integer property "foo"',
bar: 'should have a string property "bar"'
}
}
};

## Messages for properties and items

Replace errors for properties / items (and deeper), regardless where in schema they were created:

var schema = {
type: 'object',
required: ['foo', 'bar'],
allOf: [{
properties: {
foo: { type: 'integer', minimum: 2 },
bar: { type: 'string', minLength: 2 }
},
additionalProperties: false
}],
errorMessage: {
properties: {
foo: 'data.foo should be integer >= 2',
bar: 'data.bar should be string with length >= 2'
}
}
};
var validate = ajv.compile(schema);
console.log(validate({foo: 1, bar: 'a'})); // false
console.log(validate.errors); // processed errors

Processed errors:

[
{
keyword: 'errorMessage',
message: 'data.foo should be integer >= 2',
dataPath: '/foo',
// ...
params: {
errors: [
{ keyword: 'minimum' /* , ... */ }
]
},
},
{
keyword: 'errorMessage',
message: 'data.bar should be string with length >= 2',
dataPath: '/bar',
// ...
params: {
errors: [
{ keyword: 'minLength' /* , ... */ }
]
},
}
]

## Default message

When the value of keyword `errorMessage` is an object you can specify a message that will be used if any error appears that is not specified by keywords/properties/items:

var schema = {
type: 'object',
required: ['foo', 'bar'],
allOf: [{
properties: {
foo: { type: 'integer', minimum: 2 },
bar: { type: 'string', minLength: 2 }
},
additionalProperties: false
}],
errorMessage: {
type: 'data should be an object',
properties: {
foo: 'data.foo should be integer >= 2',
bar: 'data.bar should be string with length >= 2'
},
_: 'data should have properties "foo" and "bar" only'
}
};
var validate = ajv.compile(schema);
console.log(validate({})); // false
console.log(validate.errors); // processed errors

Processed errors:

[
{
keyword: 'errorMessage',
message: 'data should be an object with properties "foo" and "bar" only',
dataPath: '',
// ...
params: {
errors: [
{ keyword: 'required' /* , ... */ },
{ keyword: 'required' /* , ... */ }
]
},
}
]

The message in property `_` of `errorMessage` replaces the same errors that would have been replaced if `errorMessage` were a string.

# Templates

Custom error messages used in `errorMessage` keyword can be templates using JSON-pointers or relative JSON-pointers to data being validated, in which case the value will be interpolated. Also see examples of relative JSON-pointers.

The syntax to interpolate a value is `${<pointer>}`.

The values used in messages will be JSON-stringified:

- to differentiate between `false` and `"false"`, etc.
- to support structured values.

Example:

{
"type": "object",
"properties": {
"size": {
"type": "number",
"minimum": 4
}
},
"errorMessage": {
"properties": {
"size": "size should be a number bigger or equal to 4, current value is ${/size}"
}
}
}

# Options

Defaults:

{
keepErrors: false,
singleError: false
}

- keepErrors: keep original errors. Default is to remove matched errors (they will still be available in `params.errors` property of generated error). If an error was matched and included in the error generated by `errorMessage` keyword it will have property `emUsed: true`.
- singleError: create one error for all keywords used in `errorMessage` keyword (error messages defined for properties and items are not merged because they have different dataPaths). Multiple error messages are concatenated. Option values:
  - `false` (default): create multiple errors, one for each message
  - `true`: create single error, messages are concatenated using `"; "`
  - non-empty string: this string is used as a separator to concatenate messages

# Supporters

Roger Kepler

# License

MIT