diff options
Diffstat (limited to 'node_modules/ajv-errors/README.md')
| -rw-r--r-- | node_modules/ajv-errors/README.md | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/node_modules/ajv-errors/README.md b/node_modules/ajv-errors/README.md new file mode 100644 index 0000000..92118a4 --- /dev/null +++ b/node_modules/ajv-errors/README.md @@ -0,0 +1,318 @@ +# ajv-errors +Custom error messages in JSON-Schema for Ajv validator + +[](https://travis-ci.org/epoberezkin/ajv-errors) +[](http://badge.fury.io/js/ajv-errors) +[](https://coveralls.io/github/epoberezkin/ajv-errors?branch=master) +[](https://gitter.im/ajv-validator/ajv) + + +## Contents + +- [Install](#install) +- [Usage](#usage) + - [Single message](#single-message) + - [Messages for keywords](#messages-for-keywords) + - [Messages for properties and items](#messages-for-properties-and-items) + - [Default message](#default-message) +- [Templates](#templates) +- [Options](#options) +- [License](#license) + + +## Install + +``` +npm install ajv-errors +``` + + +## Usage + +Add the keyword `errorMessages` to Ajv instance: + +```javascript +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](#options) below. + + +### Single message + +Replace all errors in the current schema and subschemas with a single message: + +```javascript +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: + +```javascript +[ + { + 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: + +```javascript +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: + +```javascript +[ + { + // 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: + +```javascript +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: + +```javascript +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: + +```javascript +[ + { + 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: + +```javascript +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: + +```javascript +[ + { + 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](https://tools.ietf.org/html/rfc6901) or [relative JSON-pointers](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00) to data being validated, in which case the value will be interpolated. Also see [examples](https://gist.github.com/geraintluff/5911303) 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: + +```json +{ + "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: + +```javascript +{ + 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 + +[<img src="https://media.licdn.com/mpr/mpr/shrinknp_400_400/AAEAAQAAAAAAAAwEAAAAJDg1YzBlYzFjLTA3YWYtNGEzOS1iMTdjLTQ0MTU1NWZjOGM0ZQ.jpg" width="48" height="48">](https://www.linkedin.com/in/rogerkepler/) [Roger Kepler](https://www.linkedin.com/in/rogerkepler/) + + +## License + +[MIT](https://github.com/epoberezkin/ajv-errors/blob/master/LICENSE) |