twitst4tz

twitter statistics web application
Log | Files | Refs | README | LICENSE

README.md (78803B)


      1 <img align="right" alt="Ajv logo" width="160" src="http://epoberezkin.github.io/ajv/images/ajv_logo.png">
      2 
      3 # Ajv: Another JSON Schema Validator
      4 
      5 The fastest JSON Schema validator for Node.js and browser. Supports draft-04/06/07.
      6 
      7 [![Build Status](https://travis-ci.org/epoberezkin/ajv.svg?branch=master)](https://travis-ci.org/epoberezkin/ajv)
      8 [![npm](https://img.shields.io/npm/v/ajv.svg)](https://www.npmjs.com/package/ajv)
      9 [![npm downloads](https://img.shields.io/npm/dm/ajv.svg)](https://www.npmjs.com/package/ajv)
     10 [![Coverage Status](https://coveralls.io/repos/epoberezkin/ajv/badge.svg?branch=master&service=github)](https://coveralls.io/github/epoberezkin/ajv?branch=master)
     11 [![Greenkeeper badge](https://badges.greenkeeper.io/epoberezkin/ajv.svg)](https://greenkeeper.io/)
     12 [![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
     13 
     14 
     15 ## Using version 6
     16 
     17 [JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) is published.
     18 
     19 [Ajv version 6.0.0](https://github.com/epoberezkin/ajv/releases/tag/v6.0.0) that supports draft-07 is released. It may require either migrating your schemas or updating your code (to continue using draft-04 and v5 schemas, draft-06 schemas will be supported without changes).
     20 
     21 __Please note__: To use Ajv with draft-06 schemas you need to explicitly add the meta-schema to the validator instance:
     22 
     23 ```javascript
     24 ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-06.json'));
     25 ```
     26 
     27 To use Ajv with draft-04 schemas in addition to explicitly adding meta-schema you also need to use option schemaId:
     28 
     29 ```javascript
     30 var ajv = new Ajv({schemaId: 'id'});
     31 // If you want to use both draft-04 and draft-06/07 schemas:
     32 // var ajv = new Ajv({schemaId: 'auto'});
     33 ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));
     34 ```
     35 
     36 
     37 ## Contents
     38 
     39 - [Performance](#performance)
     40 - [Features](#features)
     41 - [Getting started](#getting-started)
     42 - [Frequently Asked Questions](https://github.com/epoberezkin/ajv/blob/master/FAQ.md)
     43 - [Using in browser](#using-in-browser)
     44 - [Command line interface](#command-line-interface)
     45 - Validation
     46   - [Keywords](#validation-keywords)
     47   - [Annotation keywords](#annotation-keywords)
     48   - [Formats](#formats)
     49   - [Combining schemas with $ref](#ref)
     50   - [$data reference](#data-reference)
     51   - NEW: [$merge and $patch keywords](#merge-and-patch-keywords)
     52   - [Defining custom keywords](#defining-custom-keywords)
     53   - [Asynchronous schema compilation](#asynchronous-schema-compilation)
     54   - [Asynchronous validation](#asynchronous-validation)
     55 - [Security considerations](#security-considerations)
     56   - [Security contact](#security-contact)
     57   - [Untrusted schemas](#untrusted-schemas)
     58   - [Circular references in objects](#circular-references-in-javascript-objects)
     59   - [Trusted schemas](#security-risks-of-trusted-schemas)
     60   - [ReDoS attack](#redos-attack)
     61 - Modifying data during validation
     62   - [Filtering data](#filtering-data)
     63   - [Assigning defaults](#assigning-defaults)
     64   - [Coercing data types](#coercing-data-types)
     65 - API
     66   - [Methods](#api)
     67   - [Options](#options)
     68   - [Validation errors](#validation-errors)
     69 - [Plugins](#plugins)
     70 - [Related packages](#related-packages)
     71 - [Some packages using Ajv](#some-packages-using-ajv)
     72 - [Tests, Contributing, History, Support, License](#tests)
     73 
     74 
     75 ## Performance
     76 
     77 Ajv generates code using [doT templates](https://github.com/olado/doT) to turn JSON Schemas into super-fast validation functions that are efficient for v8 optimization.
     78 
     79 Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:
     80 
     81 - [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark) - 50% faster than the second place
     82 - [jsck benchmark](https://github.com/pandastrike/jsck#benchmarks) - 20-190% faster
     83 - [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)
     84 - [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)
     85 
     86 
     87 Performance of different validators by [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark):
     88 
     89 [![performance](https://chart.googleapis.com/chart?chxt=x,y&cht=bhs&chco=76A4FB&chls=2.0&chbh=32,4,1&chs=600x416&chxl=-1:|djv|ajv|json-schema-validator-generator|jsen|is-my-json-valid|themis|z-schema|jsck|skeemas|json-schema-library|tv4&chd=t:100,98,72.1,66.8,50.1,15.1,6.1,3.8,1.2,0.7,0.2)](https://github.com/ebdrup/json-schema-benchmark/blob/master/README.md#performance)
     90 
     91 
     92 ## Features
     93 
     94 - Ajv implements full JSON Schema [draft-06/07](http://json-schema.org/) and draft-04 standards:
     95   - all validation keywords (see [JSON Schema validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md))
     96   - full support of remote refs (remote schemas have to be added with `addSchema` or compiled to be available)
     97   - support of circular references between schemas
     98   - correct string lengths for strings with unicode pairs (can be turned off)
     99   - [formats](#formats) defined by JSON Schema draft-07 standard and custom formats (can be turned off)
    100   - [validates schemas against meta-schema](#api-validateschema)
    101 - supports [browsers](#using-in-browser) and Node.js 0.10-8.x
    102 - [asynchronous loading](#asynchronous-schema-compilation) of referenced schemas during compilation
    103 - "All errors" validation mode with [option allErrors](#options)
    104 - [error messages with parameters](#validation-errors) describing error reasons to allow creating custom error messages
    105 - i18n error messages support with [ajv-i18n](https://github.com/epoberezkin/ajv-i18n) package
    106 - [filtering data](#filtering-data) from additional properties
    107 - [assigning defaults](#assigning-defaults) to missing properties and items
    108 - [coercing data](#coercing-data-types) to the types specified in `type` keywords
    109 - [custom keywords](#defining-custom-keywords)
    110 - draft-06/07 keywords `const`, `contains`, `propertyNames` and `if/then/else`
    111 - draft-06 boolean schemas (`true`/`false` as a schema to always pass/fail).
    112 - keywords `switch`, `patternRequired`, `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum` from [JSON Schema extension proposals](https://github.com/json-schema/json-schema/wiki/v5-Proposals) with [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) package
    113 - [$data reference](#data-reference) to use values from the validated data as values for the schema keywords
    114 - [asynchronous validation](#asynchronous-validation) of custom formats and keywords
    115 
    116 Currently Ajv is the only validator that passes all the tests from [JSON Schema Test Suite](https://github.com/json-schema/JSON-Schema-Test-Suite) (according to [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark), apart from the test that requires that `1.0` is not an integer that is impossible to satisfy in JavaScript).
    117 
    118 
    119 ## Install
    120 
    121 ```
    122 npm install ajv
    123 ```
    124 
    125 
    126 ## <a name="usage"></a>Getting started
    127 
    128 Try it in the Node.js REPL: https://tonicdev.com/npm/ajv
    129 
    130 
    131 The fastest validation call:
    132 
    133 ```javascript
    134 // Node.js require:
    135 var Ajv = require('ajv');
    136 // or ESM/TypeScript import
    137 import Ajv from 'ajv';
    138 
    139 var ajv = new Ajv(); // options can be passed, e.g. {allErrors: true}
    140 var validate = ajv.compile(schema);
    141 var valid = validate(data);
    142 if (!valid) console.log(validate.errors);
    143 ```
    144 
    145 or with less code
    146 
    147 ```javascript
    148 // ...
    149 var valid = ajv.validate(schema, data);
    150 if (!valid) console.log(ajv.errors);
    151 // ...
    152 ```
    153 
    154 or
    155 
    156 ```javascript
    157 // ...
    158 var valid = ajv.addSchema(schema, 'mySchema')
    159                .validate('mySchema', data);
    160 if (!valid) console.log(ajv.errorsText());
    161 // ...
    162 ```
    163 
    164 See [API](#api) and [Options](#options) for more details.
    165 
    166 Ajv compiles schemas to functions and caches them in all cases (using schema serialized with [fast-json-stable-stringify](https://github.com/epoberezkin/fast-json-stable-stringify) or a custom function as a key), so that the next time the same schema is used (not necessarily the same object instance) it won't be compiled again.
    167 
    168 The best performance is achieved when using compiled functions returned by `compile` or `getSchema` methods (there is no additional function call).
    169 
    170 __Please note__: every time a validation function or `ajv.validate` are called `errors` property is overwritten. You need to copy `errors` array reference to another variable if you want to use it later (e.g., in the callback). See [Validation errors](#validation-errors)
    171 
    172 __Note for TypeScript users__: `ajv` provides its own TypeScript declarations
    173 out of the box, so you don't need to install the deprecated `@types/ajv`
    174 module.
    175 
    176 
    177 ## Using in browser
    178 
    179 You can require Ajv directly from the code you browserify - in this case Ajv will be a part of your bundle.
    180 
    181 If you need to use Ajv in several bundles you can create a separate UMD bundle using `npm run bundle` script (thanks to [siddo420](https://github.com/siddo420)).
    182 
    183 Then you need to load Ajv in the browser:
    184 ```html
    185 <script src="ajv.min.js"></script>
    186 ```
    187 
    188 This bundle can be used with different module systems; it creates global `Ajv` if no module system is found.
    189 
    190 The browser bundle is available on [cdnjs](https://cdnjs.com/libraries/ajv).
    191 
    192 Ajv is tested with these browsers:
    193 
    194 [![Sauce Test Status](https://saucelabs.com/browser-matrix/epoberezkin.svg)](https://saucelabs.com/u/epoberezkin)
    195 
    196 __Please note__: some frameworks, e.g. Dojo, may redefine global require in such way that is not compatible with CommonJS module format. In such case Ajv bundle has to be loaded before the framework and then you can use global Ajv (see issue [#234](https://github.com/epoberezkin/ajv/issues/234)).
    197 
    198 
    199 ## Command line interface
    200 
    201 CLI is available as a separate npm package [ajv-cli](https://github.com/jessedc/ajv-cli). It supports:
    202 
    203 - compiling JSON Schemas to test their validity
    204 - BETA: generating standalone module exporting a validation function to be used without Ajv (using [ajv-pack](https://github.com/epoberezkin/ajv-pack))
    205 - migrate schemas to draft-07 (using [json-schema-migrate](https://github.com/epoberezkin/json-schema-migrate))
    206 - validating data file(s) against JSON Schema
    207 - testing expected validity of data against JSON Schema
    208 - referenced schemas
    209 - custom meta-schemas
    210 - files in JSON and JavaScript format
    211 - all Ajv options
    212 - reporting changes in data after validation in [JSON-patch](https://tools.ietf.org/html/rfc6902) format
    213 
    214 
    215 ## Validation keywords
    216 
    217 Ajv supports all validation keywords from draft-07 of JSON Schema standard:
    218 
    219 - [type](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#type)
    220 - [for numbers](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#keywords-for-numbers) - maximum, minimum, exclusiveMaximum, exclusiveMinimum, multipleOf
    221 - [for strings](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#keywords-for-strings) - maxLength, minLength, pattern, format
    222 - [for arrays](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#keywords-for-arrays) - maxItems, minItems, uniqueItems, items, additionalItems, [contains](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#contains)
    223 - [for objects](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#keywords-for-objects) - maxProperties, minProperties, required, properties, patternProperties, additionalProperties, dependencies, [propertyNames](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#propertynames)
    224 - [for all types](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#keywords-for-all-types) - enum, [const](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#const)
    225 - [compound keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#compound-keywords) - not, oneOf, anyOf, allOf, [if/then/else](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#ifthenelse)
    226 
    227 With [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) package Ajv also supports validation keywords from [JSON Schema extension proposals](https://github.com/json-schema/json-schema/wiki/v5-Proposals) for JSON Schema standard:
    228 
    229 - [patternRequired](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#patternrequired-proposed) - like `required` but with patterns that some property should match.
    230 - [formatMaximum, formatMinimum, formatExclusiveMaximum, formatExclusiveMinimum](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#formatmaximum--formatminimum-and-exclusiveformatmaximum--exclusiveformatminimum-proposed) - setting limits for date, time, etc.
    231 
    232 See [JSON Schema validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md) for more details.
    233 
    234 
    235 ## Annotation keywords
    236 
    237 JSON Schema specification defines several annotation keywords that describe schema itself but do not perform any validation.
    238 
    239 - `title` and `description`: information about the data represented by that schema
    240 - `$comment` (NEW in draft-07): information for developers. With option `$comment` Ajv logs or passes the comment string to the user-supplied function. See [Options](#options).
    241 - `default`: a default value of the data instance, see [Assigning defaults](#assigning-defaults).
    242 - `examples` (NEW in draft-06): an array of data instances. Ajv does not check the validity of these instances against the schema.
    243 - `readOnly` and `writeOnly` (NEW in draft-07): marks data-instance as read-only or write-only in relation to the source of the data (database, api, etc.).
    244 - `contentEncoding`: [RFC 2045](https://tools.ietf.org/html/rfc2045#section-6.1 ), e.g., "base64".
    245 - `contentMediaType`: [RFC 2046](https://tools.ietf.org/html/rfc2046), e.g., "image/png".
    246 
    247 __Please note__:  Ajv does not implement validation of the keywords `examples`, `contentEncoding` and `contentMediaType` but it reserves them. If you want to create a plugin that implements some of them, it should remove these keywords from the instance.
    248 
    249 
    250 ## Formats
    251 
    252 Ajv implements formats defined by JSON Schema specification and several other formats. It is recommended NOT to use "format" keyword implementations with untrusted data, as they use potentially unsafe regular expressions - see [ReDoS attack](#redos-attack).
    253 
    254 __Please note__: if you need to use "format" keyword to validate untrusted data, you MUST assess their suitability and safety for your validation scenarios.
    255 
    256 The following formats are implemented for string validation with "format" keyword:
    257 
    258 - _date_: full-date according to [RFC3339](http://tools.ietf.org/html/rfc3339#section-5.6).
    259 - _time_: time with optional time-zone.
    260 - _date-time_: date-time from the same source (time-zone is mandatory). `date`, `time` and `date-time` validate ranges in `full` mode and only regexp in `fast` mode (see [options](#options)).
    261 - _uri_: full URI.
    262 - _uri-reference_: URI reference, including full and relative URIs.
    263 - _uri-template_: URI template according to [RFC6570](https://tools.ietf.org/html/rfc6570)
    264 - _url_ (deprecated): [URL record](https://url.spec.whatwg.org/#concept-url).
    265 - _email_: email address.
    266 - _hostname_: host name according to [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5).
    267 - _ipv4_: IP address v4.
    268 - _ipv6_: IP address v6.
    269 - _regex_: tests whether a string is a valid regular expression by passing it to RegExp constructor.
    270 - _uuid_: Universally Unique IDentifier according to [RFC4122](http://tools.ietf.org/html/rfc4122).
    271 - _json-pointer_: JSON-pointer according to [RFC6901](https://tools.ietf.org/html/rfc6901).
    272 - _relative-json-pointer_: relative JSON-pointer according to [this draft](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00).
    273 
    274 __Please note__: JSON Schema draft-07 also defines formats `iri`, `iri-reference`, `idn-hostname` and `idn-email` for URLs, hostnames and emails with international characters. Ajv does not implement these formats. If you create Ajv plugin that implements them please make a PR to mention this plugin here.
    275 
    276 There are two modes of format validation: `fast` and `full`. This mode affects formats `date`, `time`, `date-time`, `uri`, `uri-reference`, `email`, and `hostname`. See [Options](#options) for details.
    277 
    278 You can add additional formats and replace any of the formats above using [addFormat](#api-addformat) method.
    279 
    280 The option `unknownFormats` allows changing the default behaviour when an unknown format is encountered. In this case Ajv can either fail schema compilation (default) or ignore it (default in versions before 5.0.0). You also can whitelist specific format(s) to be ignored. See [Options](#options) for details.
    281 
    282 You can find regular expressions used for format validation and the sources that were used in [formats.js](https://github.com/epoberezkin/ajv/blob/master/lib/compile/formats.js).
    283 
    284 
    285 ## <a name="ref"></a>Combining schemas with $ref
    286 
    287 You can structure your validation logic across multiple schema files and have schemas reference each other using `$ref` keyword.
    288 
    289 Example:
    290 
    291 ```javascript
    292 var schema = {
    293   "$id": "http://example.com/schemas/schema.json",
    294   "type": "object",
    295   "properties": {
    296     "foo": { "$ref": "defs.json#/definitions/int" },
    297     "bar": { "$ref": "defs.json#/definitions/str" }
    298   }
    299 };
    300 
    301 var defsSchema = {
    302   "$id": "http://example.com/schemas/defs.json",
    303   "definitions": {
    304     "int": { "type": "integer" },
    305     "str": { "type": "string" }
    306   }
    307 };
    308 ```
    309 
    310 Now to compile your schema you can either pass all schemas to Ajv instance:
    311 
    312 ```javascript
    313 var ajv = new Ajv({schemas: [schema, defsSchema]});
    314 var validate = ajv.getSchema('http://example.com/schemas/schema.json');
    315 ```
    316 
    317 or use `addSchema` method:
    318 
    319 ```javascript
    320 var ajv = new Ajv;
    321 var validate = ajv.addSchema(defsSchema)
    322                   .compile(schema);
    323 ```
    324 
    325 See [Options](#options) and [addSchema](#api) method.
    326 
    327 __Please note__:
    328 - `$ref` is resolved as the uri-reference using schema $id as the base URI (see the example).
    329 - References can be recursive (and mutually recursive) to implement the schemas for different data structures (such as linked lists, trees, graphs, etc.).
    330 - You don't have to host your schema files at the URIs that you use as schema $id. These URIs are only used to identify the schemas, and according to JSON Schema specification validators should not expect to be able to download the schemas from these URIs.
    331 - The actual location of the schema file in the file system is not used.
    332 - You can pass the identifier of the schema as the second parameter of `addSchema` method or as a property name in `schemas` option. This identifier can be used instead of (or in addition to) schema $id.
    333 - You cannot have the same $id (or the schema identifier) used for more than one schema - the exception will be thrown.
    334 - You can implement dynamic resolution of the referenced schemas using `compileAsync` method. In this way you can store schemas in any system (files, web, database, etc.) and reference them without explicitly adding to Ajv instance. See [Asynchronous schema compilation](#asynchronous-schema-compilation).
    335 
    336 
    337 ## $data reference
    338 
    339 With `$data` option you can use values from the validated data as the values for the schema keywords. See [proposal](https://github.com/json-schema-org/json-schema-spec/issues/51) for more information about how it works.
    340 
    341 `$data` reference is supported in the keywords: const, enum, format, maximum/minimum, exclusiveMaximum / exclusiveMinimum, maxLength / minLength, maxItems / minItems, maxProperties / minProperties, formatMaximum / formatMinimum, formatExclusiveMaximum / formatExclusiveMinimum, multipleOf, pattern, required, uniqueItems.
    342 
    343 The value of "$data" should be a [JSON-pointer](https://tools.ietf.org/html/rfc6901) to the data (the root is always the top level data object, even if the $data reference is inside a referenced subschema) or a [relative JSON-pointer](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00) (it is relative to the current point in data; if the $data reference is inside a referenced subschema it cannot point to the data outside of the root level for this subschema).
    344 
    345 Examples.
    346 
    347 This schema requires that the value in property `smaller` is less or equal than the value in the property larger:
    348 
    349 ```javascript
    350 var ajv = new Ajv({$data: true});
    351 
    352 var schema = {
    353   "properties": {
    354     "smaller": {
    355       "type": "number",
    356       "maximum": { "$data": "1/larger" }
    357     },
    358     "larger": { "type": "number" }
    359   }
    360 };
    361 
    362 var validData = {
    363   smaller: 5,
    364   larger: 7
    365 };
    366 
    367 ajv.validate(schema, validData); // true
    368 ```
    369 
    370 This schema requires that the properties have the same format as their field names:
    371 
    372 ```javascript
    373 var schema = {
    374   "additionalProperties": {
    375     "type": "string",
    376     "format": { "$data": "0#" }
    377   }
    378 };
    379 
    380 var validData = {
    381   'date-time': '1963-06-19T08:30:06.283185Z',
    382   email: 'joe.bloggs@example.com'
    383 }
    384 ```
    385 
    386 `$data` reference is resolved safely - it won't throw even if some property is undefined. If `$data` resolves to `undefined` the validation succeeds (with the exclusion of `const` keyword). If `$data` resolves to incorrect type (e.g. not "number" for maximum keyword) the validation fails.
    387 
    388 
    389 ## $merge and $patch keywords
    390 
    391 With the package [ajv-merge-patch](https://github.com/epoberezkin/ajv-merge-patch) you can use the keywords `$merge` and `$patch` that allow extending JSON Schemas with patches using formats [JSON Merge Patch (RFC 7396)](https://tools.ietf.org/html/rfc7396) and [JSON Patch (RFC 6902)](https://tools.ietf.org/html/rfc6902).
    392 
    393 To add keywords `$merge` and `$patch` to Ajv instance use this code:
    394 
    395 ```javascript
    396 require('ajv-merge-patch')(ajv);
    397 ```
    398 
    399 Examples.
    400 
    401 Using `$merge`:
    402 
    403 ```json
    404 {
    405   "$merge": {
    406     "source": {
    407       "type": "object",
    408       "properties": { "p": { "type": "string" } },
    409       "additionalProperties": false
    410     },
    411     "with": {
    412       "properties": { "q": { "type": "number" } }
    413     }
    414   }
    415 }
    416 ```
    417 
    418 Using `$patch`:
    419 
    420 ```json
    421 {
    422   "$patch": {
    423     "source": {
    424       "type": "object",
    425       "properties": { "p": { "type": "string" } },
    426       "additionalProperties": false
    427     },
    428     "with": [
    429       { "op": "add", "path": "/properties/q", "value": { "type": "number" } }
    430     ]
    431   }
    432 }
    433 ```
    434 
    435 The schemas above are equivalent to this schema:
    436 
    437 ```json
    438 {
    439   "type": "object",
    440   "properties": {
    441     "p": { "type": "string" },
    442     "q": { "type": "number" }
    443   },
    444   "additionalProperties": false
    445 }
    446 ```
    447 
    448 The properties `source` and `with` in the keywords `$merge` and `$patch` can use absolute or relative `$ref` to point to other schemas previously added to the Ajv instance or to the fragments of the current schema.
    449 
    450 See the package [ajv-merge-patch](https://github.com/epoberezkin/ajv-merge-patch) for more information.
    451 
    452 
    453 ## Defining custom keywords
    454 
    455 The advantages of using custom keywords are:
    456 
    457 - allow creating validation scenarios that cannot be expressed using JSON Schema
    458 - simplify your schemas
    459 - help bringing a bigger part of the validation logic to your schemas
    460 - make your schemas more expressive, less verbose and closer to your application domain
    461 - implement custom data processors that modify your data (`modifying` option MUST be used in keyword definition) and/or create side effects while the data is being validated
    462 
    463 If a keyword is used only for side-effects and its validation result is pre-defined, use option `valid: true/false` in keyword definition to simplify both generated code (no error handling in case of `valid: true`) and your keyword functions (no need to return any validation result).
    464 
    465 The concerns you have to be aware of when extending JSON Schema standard with custom keywords are the portability and understanding of your schemas. You will have to support these custom keywords on other platforms and to properly document these keywords so that everybody can understand them in your schemas.
    466 
    467 You can define custom keywords with [addKeyword](#api-addkeyword) method. Keywords are defined on the `ajv` instance level - new instances will not have previously defined keywords.
    468 
    469 Ajv allows defining keywords with:
    470 - validation function
    471 - compilation function
    472 - macro function
    473 - inline compilation function that should return code (as string) that will be inlined in the currently compiled schema.
    474 
    475 Example. `range` and `exclusiveRange` keywords using compiled schema:
    476 
    477 ```javascript
    478 ajv.addKeyword('range', {
    479   type: 'number',
    480   compile: function (sch, parentSchema) {
    481     var min = sch[0];
    482     var max = sch[1];
    483 
    484     return parentSchema.exclusiveRange === true
    485             ? function (data) { return data > min && data < max; }
    486             : function (data) { return data >= min && data <= max; }
    487   }
    488 });
    489 
    490 var schema = { "range": [2, 4], "exclusiveRange": true };
    491 var validate = ajv.compile(schema);
    492 console.log(validate(2.01)); // true
    493 console.log(validate(3.99)); // true
    494 console.log(validate(2)); // false
    495 console.log(validate(4)); // false
    496 ```
    497 
    498 Several custom keywords (typeof, instanceof, range and propertyNames) are defined in [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) package - they can be used for your schemas and as a starting point for your own custom keywords.
    499 
    500 See [Defining custom keywords](https://github.com/epoberezkin/ajv/blob/master/CUSTOM.md) for more details.
    501 
    502 
    503 ## Asynchronous schema compilation
    504 
    505 During asynchronous compilation remote references are loaded using supplied function. See `compileAsync` [method](#api-compileAsync) and `loadSchema` [option](#options).
    506 
    507 Example:
    508 
    509 ```javascript
    510 var ajv = new Ajv({ loadSchema: loadSchema });
    511 
    512 ajv.compileAsync(schema).then(function (validate) {
    513   var valid = validate(data);
    514   // ...
    515 });
    516 
    517 function loadSchema(uri) {
    518   return request.json(uri).then(function (res) {
    519     if (res.statusCode >= 400)
    520       throw new Error('Loading error: ' + res.statusCode);
    521     return res.body;
    522   });
    523 }
    524 ```
    525 
    526 __Please note__: [Option](#options) `missingRefs` should NOT be set to `"ignore"` or `"fail"` for asynchronous compilation to work.
    527 
    528 
    529 ## Asynchronous validation
    530 
    531 Example in Node.js REPL: https://tonicdev.com/esp/ajv-asynchronous-validation
    532 
    533 You can define custom formats and keywords that perform validation asynchronously by accessing database or some other service. You should add `async: true` in the keyword or format definition (see [addFormat](#api-addformat), [addKeyword](#api-addkeyword) and [Defining custom keywords](#defining-custom-keywords)).
    534 
    535 If your schema uses asynchronous formats/keywords or refers to some schema that contains them it should have `"$async": true` keyword so that Ajv can compile it correctly. If asynchronous format/keyword or reference to asynchronous schema is used in the schema without `$async` keyword Ajv will throw an exception during schema compilation.
    536 
    537 __Please note__: all asynchronous subschemas that are referenced from the current or other schemas should have `"$async": true` keyword as well, otherwise the schema compilation will fail.
    538 
    539 Validation function for an asynchronous custom format/keyword should return a promise that resolves with `true` or `false` (or rejects with `new Ajv.ValidationError(errors)` if you want to return custom errors from the keyword function).
    540 
    541 Ajv compiles asynchronous schemas to [es7 async functions](http://tc39.github.io/ecmascript-asyncawait/) that can optionally be transpiled with [nodent](https://github.com/MatAtBread/nodent). Async functions are supported in Node.js 7+ and all modern browsers. You can also supply any other transpiler as a function via `processCode` option. See [Options](#options).
    542 
    543 The compiled validation function has `$async: true` property (if the schema is asynchronous), so you can differentiate these functions if you are using both synchronous and asynchronous schemas.
    544 
    545 Validation result will be a promise that resolves with validated data or rejects with an exception `Ajv.ValidationError` that contains the array of validation errors in `errors` property.
    546 
    547 
    548 Example:
    549 
    550 ```javascript
    551 var ajv = new Ajv;
    552 // require('ajv-async')(ajv);
    553 
    554 ajv.addKeyword('idExists', {
    555   async: true,
    556   type: 'number',
    557   validate: checkIdExists
    558 });
    559 
    560 
    561 function checkIdExists(schema, data) {
    562   return knex(schema.table)
    563   .select('id')
    564   .where('id', data)
    565   .then(function (rows) {
    566     return !!rows.length; // true if record is found
    567   });
    568 }
    569 
    570 var schema = {
    571   "$async": true,
    572   "properties": {
    573     "userId": {
    574       "type": "integer",
    575       "idExists": { "table": "users" }
    576     },
    577     "postId": {
    578       "type": "integer",
    579       "idExists": { "table": "posts" }
    580     }
    581   }
    582 };
    583 
    584 var validate = ajv.compile(schema);
    585 
    586 validate({ userId: 1, postId: 19 })
    587 .then(function (data) {
    588   console.log('Data is valid', data); // { userId: 1, postId: 19 }
    589 })
    590 .catch(function (err) {
    591   if (!(err instanceof Ajv.ValidationError)) throw err;
    592   // data is invalid
    593   console.log('Validation errors:', err.errors);
    594 });
    595 ```
    596 
    597 ### Using transpilers with asynchronous validation functions.
    598 
    599 [ajv-async](https://github.com/epoberezkin/ajv-async) uses [nodent](https://github.com/MatAtBread/nodent) to transpile async functions. To use another transpiler you should separately install it (or load its bundle in the browser).
    600 
    601 
    602 #### Using nodent
    603 
    604 ```javascript
    605 var ajv = new Ajv;
    606 require('ajv-async')(ajv);
    607 // in the browser if you want to load ajv-async bundle separately you can:
    608 // window.ajvAsync(ajv);
    609 var validate = ajv.compile(schema); // transpiled es7 async function
    610 validate(data).then(successFunc).catch(errorFunc);
    611 ```
    612 
    613 
    614 #### Using other transpilers
    615 
    616 ```javascript
    617 var ajv = new Ajv({ processCode: transpileFunc });
    618 var validate = ajv.compile(schema); // transpiled es7 async function
    619 validate(data).then(successFunc).catch(errorFunc);
    620 ```
    621 
    622 See [Options](#options).
    623 
    624 
    625 ## Security considerations
    626 
    627 JSON Schema, if properly used, can replace data sanitisation. It doesn't replace other API security considerations. It also introduces additional security aspects to consider.
    628 
    629 
    630 ##### Security contact
    631 
    632 To report a security vulnerability, please use the
    633 [Tidelift security contact](https://tidelift.com/security).
    634 Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.
    635 
    636 
    637 ##### Untrusted schemas
    638 
    639 Ajv treats JSON schemas as trusted as your application code. This security model is based on the most common use case, when the schemas are static and bundled together with the application.
    640 
    641 If your schemas are received from untrusted sources (or generated from untrusted data) there are several scenarios you need to prevent:
    642 - compiling schemas can cause stack overflow (if they are too deep)
    643 - compiling schemas can be slow (e.g. [#557](https://github.com/epoberezkin/ajv/issues/557))
    644 - validating certain data can be slow
    645 
    646 It is difficult to predict all the scenarios, but at the very least it may help to limit the size of untrusted schemas (e.g. limit JSON string length) and also the maximum schema object depth (that can be high for relatively small JSON strings). You also may want to mitigate slow regular expressions in `pattern` and `patternProperties` keywords.
    647 
    648 Regardless the measures you take, using untrusted schemas increases security risks.
    649 
    650 
    651 ##### Circular references in JavaScript objects
    652 
    653 Ajv does not support schemas and validated data that have circular references in objects. See [issue #802](https://github.com/epoberezkin/ajv/issues/802).
    654 
    655 An attempt to compile such schemas or validate such data would cause stack overflow (or will not complete in case of asynchronous validation). Depending on the parser you use, untrusted data can lead to circular references.
    656 
    657 
    658 ##### Security risks of trusted schemas
    659 
    660 Some keywords in JSON Schemas can lead to very slow validation for certain data. These keywords include (but may be not limited to):
    661 
    662 - `pattern` and `format` for large strings - in some cases using `maxLength` can help mitigate it, but certain regular expressions can lead to exponential validation time even with relatively short strings (see [ReDoS attack](#redos-attack)).
    663 - `patternProperties` for large property names - use `propertyNames` to mitigate, but some regular expressions can have exponential evaluation time as well.
    664 - `uniqueItems` for large non-scalar arrays - use `maxItems` to mitigate
    665 
    666 __Please note__: The suggestions above to prevent slow validation would only work if you do NOT use `allErrors: true` in production code (using it would continue validation after validation errors).
    667 
    668 You can validate your JSON schemas against [this meta-schema](https://github.com/epoberezkin/ajv/blob/master/lib/refs/json-schema-secure.json) to check that these recommendations are followed:
    669 
    670 ```javascript
    671 const isSchemaSecure = ajv.compile(require('ajv/lib/refs/json-schema-secure.json'));
    672 
    673 const schema1 = {format: 'email'};
    674 isSchemaSecure(schema1); // false
    675 
    676 const schema2 = {format: 'email', maxLength: MAX_LENGTH};
    677 isSchemaSecure(schema2); // true
    678 ```
    679 
    680 __Please note__: following all these recommendation is not a guarantee that validation of untrusted data is safe - it can still lead to some undesirable results.
    681 
    682 
    683 ## ReDoS attack
    684 
    685 Certain regular expressions can lead to the exponential evaluation time even with relatively short strings.
    686 
    687 Please assess the regular expressions you use in the schemas on their vulnerability to this attack - see [safe-regex](https://github.com/substack/safe-regex), for example.
    688 
    689 __Please note__: some formats that Ajv implements use [regular expressions](https://github.com/epoberezkin/ajv/blob/master/lib/compile/formats.js) that can be vulnerable to ReDoS attack, so if you use Ajv to validate data from untrusted sources __it is strongly recommended__ to consider the following:
    690 
    691 - making assessment of "format" implementations in Ajv.
    692 - using `format: 'fast'` option that simplifies some of the regular expressions (although it does not guarantee that they are safe).
    693 - replacing format implementations provided by Ajv with your own implementations of "format" keyword that either uses different regular expressions or another approach to format validation. Please see [addFormat](#api-addformat) method.
    694 - disabling format validation by ignoring "format" keyword with option `format: false`
    695 
    696 Whatever mitigation you choose, please assume all formats provided by Ajv as potentially unsafe and make your own assessment of their suitability for your validation scenarios.
    697 
    698 
    699 ## Filtering data
    700 
    701 With [option `removeAdditional`](#options) (added by [andyscott](https://github.com/andyscott)) you can filter data during the validation.
    702 
    703 This option modifies original data.
    704 
    705 Example:
    706 
    707 ```javascript
    708 var ajv = new Ajv({ removeAdditional: true });
    709 var schema = {
    710   "additionalProperties": false,
    711   "properties": {
    712     "foo": { "type": "number" },
    713     "bar": {
    714       "additionalProperties": { "type": "number" },
    715       "properties": {
    716         "baz": { "type": "string" }
    717       }
    718     }
    719   }
    720 }
    721 
    722 var data = {
    723   "foo": 0,
    724   "additional1": 1, // will be removed; `additionalProperties` == false
    725   "bar": {
    726     "baz": "abc",
    727     "additional2": 2 // will NOT be removed; `additionalProperties` != false
    728   },
    729 }
    730 
    731 var validate = ajv.compile(schema);
    732 
    733 console.log(validate(data)); // true
    734 console.log(data); // { "foo": 0, "bar": { "baz": "abc", "additional2": 2 }
    735 ```
    736 
    737 If `removeAdditional` option in the example above were `"all"` then both `additional1` and `additional2` properties would have been removed.
    738 
    739 If the option were `"failing"` then property `additional1` would have been removed regardless of its value and property `additional2` would have been removed only if its value were failing the schema in the inner `additionalProperties` (so in the example above it would have stayed because it passes the schema, but any non-number would have been removed).
    740 
    741 __Please note__: If you use `removeAdditional` option with `additionalProperties` keyword inside `anyOf`/`oneOf` keywords your validation can fail with this schema, for example:
    742 
    743 ```json
    744 {
    745   "type": "object",
    746   "oneOf": [
    747     {
    748       "properties": {
    749         "foo": { "type": "string" }
    750       },
    751       "required": [ "foo" ],
    752       "additionalProperties": false
    753     },
    754     {
    755       "properties": {
    756         "bar": { "type": "integer" }
    757       },
    758       "required": [ "bar" ],
    759       "additionalProperties": false
    760     }
    761   ]
    762 }
    763 ```
    764 
    765 The intention of the schema above is to allow objects with either the string property "foo" or the integer property "bar", but not with both and not with any other properties.
    766 
    767 With the option `removeAdditional: true` the validation will pass for the object `{ "foo": "abc"}` but will fail for the object `{"bar": 1}`. It happens because while the first subschema in `oneOf` is validated, the property `bar` is removed because it is an additional property according to the standard (because it is not included in `properties` keyword in the same schema).
    768 
    769 While this behaviour is unexpected (issues [#129](https://github.com/epoberezkin/ajv/issues/129), [#134](https://github.com/epoberezkin/ajv/issues/134)), it is correct. To have the expected behaviour (both objects are allowed and additional properties are removed) the schema has to be refactored in this way:
    770 
    771 ```json
    772 {
    773   "type": "object",
    774   "properties": {
    775     "foo": { "type": "string" },
    776     "bar": { "type": "integer" }
    777   },
    778   "additionalProperties": false,
    779   "oneOf": [
    780     { "required": [ "foo" ] },
    781     { "required": [ "bar" ] }
    782   ]
    783 }
    784 ```
    785 
    786 The schema above is also more efficient - it will compile into a faster function.
    787 
    788 
    789 ## Assigning defaults
    790 
    791 With [option `useDefaults`](#options) Ajv will assign values from `default` keyword in the schemas of `properties` and `items` (when it is the array of schemas) to the missing properties and items.
    792 
    793 With the option value `"empty"` properties and items equal to `null` or `""` (empty string) will be considered missing and assigned defaults.
    794 
    795 This option modifies original data.
    796 
    797 __Please note__: the default value is inserted in the generated validation code as a literal, so the value inserted in the data will be the deep clone of the default in the schema.
    798 
    799 
    800 Example 1 (`default` in `properties`):
    801 
    802 ```javascript
    803 var ajv = new Ajv({ useDefaults: true });
    804 var schema = {
    805   "type": "object",
    806   "properties": {
    807     "foo": { "type": "number" },
    808     "bar": { "type": "string", "default": "baz" }
    809   },
    810   "required": [ "foo", "bar" ]
    811 };
    812 
    813 var data = { "foo": 1 };
    814 
    815 var validate = ajv.compile(schema);
    816 
    817 console.log(validate(data)); // true
    818 console.log(data); // { "foo": 1, "bar": "baz" }
    819 ```
    820 
    821 Example 2 (`default` in `items`):
    822 
    823 ```javascript
    824 var schema = {
    825   "type": "array",
    826   "items": [
    827     { "type": "number" },
    828     { "type": "string", "default": "foo" }
    829   ]
    830 }
    831 
    832 var data = [ 1 ];
    833 
    834 var validate = ajv.compile(schema);
    835 
    836 console.log(validate(data)); // true
    837 console.log(data); // [ 1, "foo" ]
    838 ```
    839 
    840 `default` keywords in other cases are ignored:
    841 
    842 - not in `properties` or `items` subschemas
    843 - in schemas inside `anyOf`, `oneOf` and `not` (see [#42](https://github.com/epoberezkin/ajv/issues/42))
    844 - in `if` subschema of `switch` keyword
    845 - in schemas generated by custom macro keywords
    846 
    847 The [`strictDefaults` option](#options) customizes Ajv's behavior for the defaults that Ajv ignores (`true` raises an error, and `"log"` outputs a warning).
    848 
    849 
    850 ## Coercing data types
    851 
    852 When you are validating user inputs all your data properties are usually strings. The option `coerceTypes` allows you to have your data types coerced to the types specified in your schema `type` keywords, both to pass the validation and to use the correctly typed data afterwards.
    853 
    854 This option modifies original data.
    855 
    856 __Please note__: if you pass a scalar value to the validating function its type will be coerced and it will pass the validation, but the value of the variable you pass won't be updated because scalars are passed by value.
    857 
    858 
    859 Example 1:
    860 
    861 ```javascript
    862 var ajv = new Ajv({ coerceTypes: true });
    863 var schema = {
    864   "type": "object",
    865   "properties": {
    866     "foo": { "type": "number" },
    867     "bar": { "type": "boolean" }
    868   },
    869   "required": [ "foo", "bar" ]
    870 };
    871 
    872 var data = { "foo": "1", "bar": "false" };
    873 
    874 var validate = ajv.compile(schema);
    875 
    876 console.log(validate(data)); // true
    877 console.log(data); // { "foo": 1, "bar": false }
    878 ```
    879 
    880 Example 2 (array coercions):
    881 
    882 ```javascript
    883 var ajv = new Ajv({ coerceTypes: 'array' });
    884 var schema = {
    885   "properties": {
    886     "foo": { "type": "array", "items": { "type": "number" } },
    887     "bar": { "type": "boolean" }
    888   }
    889 };
    890 
    891 var data = { "foo": "1", "bar": ["false"] };
    892 
    893 var validate = ajv.compile(schema);
    894 
    895 console.log(validate(data)); // true
    896 console.log(data); // { "foo": [1], "bar": false }
    897 ```
    898 
    899 The coercion rules, as you can see from the example, are different from JavaScript both to validate user input as expected and to have the coercion reversible (to correctly validate cases where different types are defined in subschemas of "anyOf" and other compound keywords).
    900 
    901 See [Coercion rules](https://github.com/epoberezkin/ajv/blob/master/COERCION.md) for details.
    902 
    903 
    904 ## API
    905 
    906 ##### new Ajv(Object options) -&gt; Object
    907 
    908 Create Ajv instance.
    909 
    910 
    911 ##### .compile(Object schema) -&gt; Function&lt;Object data&gt;
    912 
    913 Generate validating function and cache the compiled schema for future use.
    914 
    915 Validating function returns a boolean value. This function has properties `errors` and `schema`. Errors encountered during the last validation are assigned to `errors` property (it is assigned `null` if there was no errors). `schema` property contains the reference to the original schema.
    916 
    917 The schema passed to this method will be validated against meta-schema unless `validateSchema` option is false. If schema is invalid, an error will be thrown. See [options](#options).
    918 
    919 
    920 ##### <a name="api-compileAsync"></a>.compileAsync(Object schema [, Boolean meta] [, Function callback]) -&gt; Promise
    921 
    922 Asynchronous version of `compile` method that loads missing remote schemas using asynchronous function in `options.loadSchema`. This function returns a Promise that resolves to a validation function. An optional callback passed to `compileAsync` will be called with 2 parameters: error (or null) and validating function. The returned promise will reject (and the callback will be called with an error) when:
    923 
    924 - missing schema can't be loaded (`loadSchema` returns a Promise that rejects).
    925 - a schema containing a missing reference is loaded, but the reference cannot be resolved.
    926 - schema (or some loaded/referenced schema) is invalid.
    927 
    928 The function compiles schema and loads the first missing schema (or meta-schema) until all missing schemas are loaded.
    929 
    930 You can asynchronously compile meta-schema by passing `true` as the second parameter.
    931 
    932 See example in [Asynchronous compilation](#asynchronous-schema-compilation).
    933 
    934 
    935 ##### .validate(Object schema|String key|String ref, data) -&gt; Boolean
    936 
    937 Validate data using passed schema (it will be compiled and cached).
    938 
    939 Instead of the schema you can use the key that was previously passed to `addSchema`, the schema id if it was present in the schema or any previously resolved reference.
    940 
    941 Validation errors will be available in the `errors` property of Ajv instance (`null` if there were no errors).
    942 
    943 __Please note__: every time this method is called the errors are overwritten so you need to copy them to another variable if you want to use them later.
    944 
    945 If the schema is asynchronous (has `$async` keyword on the top level) this method returns a Promise. See [Asynchronous validation](#asynchronous-validation).
    946 
    947 
    948 ##### .addSchema(Array&lt;Object&gt;|Object schema [, String key]) -&gt; Ajv
    949 
    950 Add schema(s) to validator instance. This method does not compile schemas (but it still validates them). Because of that dependencies can be added in any order and circular dependencies are supported. It also prevents unnecessary compilation of schemas that are containers for other schemas but not used as a whole.
    951 
    952 Array of schemas can be passed (schemas should have ids), the second parameter will be ignored.
    953 
    954 Key can be passed that can be used to reference the schema and will be used as the schema id if there is no id inside the schema. If the key is not passed, the schema id will be used as the key.
    955 
    956 
    957 Once the schema is added, it (and all the references inside it) can be referenced in other schemas and used to validate data.
    958 
    959 Although `addSchema` does not compile schemas, explicit compilation is not required - the schema will be compiled when it is used first time.
    960 
    961 By default the schema is validated against meta-schema before it is added, and if the schema does not pass validation the exception is thrown. This behaviour is controlled by `validateSchema` option.
    962 
    963 __Please note__: Ajv uses the [method chaining syntax](https://en.wikipedia.org/wiki/Method_chaining) for all methods with the prefix `add*` and `remove*`.
    964 This allows you to do nice things like the following.
    965 
    966 ```javascript
    967 var validate = new Ajv().addSchema(schema).addFormat(name, regex).getSchema(uri);
    968 ```
    969 
    970 ##### .addMetaSchema(Array&lt;Object&gt;|Object schema [, String key]) -&gt; Ajv
    971 
    972 Adds meta schema(s) that can be used to validate other schemas. That function should be used instead of `addSchema` because there may be instance options that would compile a meta schema incorrectly (at the moment it is `removeAdditional` option).
    973 
    974 There is no need to explicitly add draft-07 meta schema (http://json-schema.org/draft-07/schema) - it is added by default, unless option `meta` is set to `false`. You only need to use it if you have a changed meta-schema that you want to use to validate your schemas. See `validateSchema`.
    975 
    976 
    977 ##### <a name="api-validateschema"></a>.validateSchema(Object schema) -&gt; Boolean
    978 
    979 Validates schema. This method should be used to validate schemas rather than `validate` due to the inconsistency of `uri` format in JSON Schema standard.
    980 
    981 By default this method is called automatically when the schema is added, so you rarely need to use it directly.
    982 
    983 If schema doesn't have `$schema` property, it is validated against draft 6 meta-schema (option `meta` should not be false).
    984 
    985 If schema has `$schema` property, then the schema with this id (that should be previously added) is used to validate passed schema.
    986 
    987 Errors will be available at `ajv.errors`.
    988 
    989 
    990 ##### .getSchema(String key) -&gt; Function&lt;Object data&gt;
    991 
    992 Retrieve compiled schema previously added with `addSchema` by the key passed to `addSchema` or by its full reference (id). The returned validating function has `schema` property with the reference to the original schema.
    993 
    994 
    995 ##### .removeSchema([Object schema|String key|String ref|RegExp pattern]) -&gt; Ajv
    996 
    997 Remove added/cached schema. Even if schema is referenced by other schemas it can be safely removed as dependent schemas have local references.
    998 
    999 Schema can be removed using:
   1000 - key passed to `addSchema`
   1001 - it's full reference (id)
   1002 - RegExp that should match schema id or key (meta-schemas won't be removed)
   1003 - actual schema object that will be stable-stringified to remove schema from cache
   1004 
   1005 If no parameter is passed all schemas but meta-schemas will be removed and the cache will be cleared.
   1006 
   1007 
   1008 ##### <a name="api-addformat"></a>.addFormat(String name, String|RegExp|Function|Object format) -&gt; Ajv
   1009 
   1010 Add custom format to validate strings or numbers. It can also be used to replace pre-defined formats for Ajv instance.
   1011 
   1012 Strings are converted to RegExp.
   1013 
   1014 Function should return validation result as `true` or `false`.
   1015 
   1016 If object is passed it should have properties `validate`, `compare` and `async`:
   1017 
   1018 - _validate_: a string, RegExp or a function as described above.
   1019 - _compare_: an optional comparison function that accepts two strings and compares them according to the format meaning. This function is used with keywords `formatMaximum`/`formatMinimum` (defined in [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) package). It should return `1` if the first value is bigger than the second value, `-1` if it is smaller and `0` if it is equal.
   1020 - _async_: an optional `true` value if `validate` is an asynchronous function; in this case it should return a promise that resolves with a value `true` or `false`.
   1021 - _type_: an optional type of data that the format applies to. It can be `"string"` (default) or `"number"` (see https://github.com/epoberezkin/ajv/issues/291#issuecomment-259923858). If the type of data is different, the validation will pass.
   1022 
   1023 Custom formats can be also added via `formats` option.
   1024 
   1025 
   1026 ##### <a name="api-addkeyword"></a>.addKeyword(String keyword, Object definition) -&gt; Ajv
   1027 
   1028 Add custom validation keyword to Ajv instance.
   1029 
   1030 Keyword should be different from all standard JSON Schema keywords and different from previously defined keywords. There is no way to redefine keywords or to remove keyword definition from the instance.
   1031 
   1032 Keyword must start with a letter, `_` or `$`, and may continue with letters, numbers, `_`, `$`, or `-`.
   1033 It is recommended to use an application-specific prefix for keywords to avoid current and future name collisions.
   1034 
   1035 Example Keywords:
   1036 - `"xyz-example"`: valid, and uses prefix for the xyz project to avoid name collisions.
   1037 - `"example"`: valid, but not recommended as it could collide with future versions of JSON Schema etc.
   1038 - `"3-example"`: invalid as numbers are not allowed to be the first character in a keyword
   1039 
   1040 Keyword definition is an object with the following properties:
   1041 
   1042 - _type_: optional string or array of strings with data type(s) that the keyword applies to. If not present, the keyword will apply to all types.
   1043 - _validate_: validating function
   1044 - _compile_: compiling function
   1045 - _macro_: macro function
   1046 - _inline_: compiling function that returns code (as string)
   1047 - _schema_: an optional `false` value used with "validate" keyword to not pass schema
   1048 - _metaSchema_: an optional meta-schema for keyword schema
   1049 - _dependencies_: an optional list of properties that must be present in the parent schema - it will be checked during schema compilation
   1050 - _modifying_: `true` MUST be passed if keyword modifies data
   1051 - _statements_: `true` can be passed in case inline keyword generates statements (as opposed to expression)
   1052 - _valid_: pass `true`/`false` to pre-define validation result, the result returned from validation function will be ignored. This option cannot be used with macro keywords.
   1053 - _$data_: an optional `true` value to support [$data reference](#data-reference) as the value of custom keyword. The reference will be resolved at validation time. If the keyword has meta-schema it would be extended to allow $data and it will be used to validate the resolved value. Supporting $data reference requires that keyword has validating function (as the only option or in addition to compile, macro or inline function).
   1054 - _async_: an optional `true` value if the validation function is asynchronous (whether it is compiled or passed in _validate_ property); in this case it should return a promise that resolves with a value `true` or `false`. This option is ignored in case of "macro" and "inline" keywords.
   1055 - _errors_: an optional boolean or string `"full"` indicating whether keyword returns errors. If this property is not set Ajv will determine if the errors were set in case of failed validation.
   1056 
   1057 _compile_, _macro_ and _inline_ are mutually exclusive, only one should be used at a time. _validate_ can be used separately or in addition to them to support $data reference.
   1058 
   1059 __Please note__: If the keyword is validating data type that is different from the type(s) in its definition, the validation function will not be called (and expanded macro will not be used), so there is no need to check for data type inside validation function or inside schema returned by macro function (unless you want to enforce a specific type and for some reason do not want to use a separate `type` keyword for that). In the same way as standard keywords work, if the keyword does not apply to the data type being validated, the validation of this keyword will succeed.
   1060 
   1061 See [Defining custom keywords](#defining-custom-keywords) for more details.
   1062 
   1063 
   1064 ##### .getKeyword(String keyword) -&gt; Object|Boolean
   1065 
   1066 Returns custom keyword definition, `true` for pre-defined keywords and `false` if the keyword is unknown.
   1067 
   1068 
   1069 ##### .removeKeyword(String keyword) -&gt; Ajv
   1070 
   1071 Removes custom or pre-defined keyword so you can redefine them.
   1072 
   1073 While this method can be used to extend pre-defined keywords, it can also be used to completely change their meaning - it may lead to unexpected results.
   1074 
   1075 __Please note__: schemas compiled before the keyword is removed will continue to work without changes. To recompile schemas use `removeSchema` method and compile them again.
   1076 
   1077 
   1078 ##### .errorsText([Array&lt;Object&gt; errors [, Object options]]) -&gt; String
   1079 
   1080 Returns the text with all errors in a String.
   1081 
   1082 Options can have properties `separator` (string used to separate errors, ", " by default) and `dataVar` (the variable name that dataPaths are prefixed with, "data" by default).
   1083 
   1084 
   1085 ## Options
   1086 
   1087 Defaults:
   1088 
   1089 ```javascript
   1090 {
   1091   // validation and reporting options:
   1092   $data:            false,
   1093   allErrors:        false,
   1094   verbose:          false,
   1095   $comment:         false, // NEW in Ajv version 6.0
   1096   jsonPointers:     false,
   1097   uniqueItems:      true,
   1098   unicode:          true,
   1099   nullable:         false,
   1100   format:           'fast',
   1101   formats:          {},
   1102   unknownFormats:   true,
   1103   schemas:          {},
   1104   logger:           undefined,
   1105   // referenced schema options:
   1106   schemaId:         '$id',
   1107   missingRefs:      true,
   1108   extendRefs:       'ignore', // recommended 'fail'
   1109   loadSchema:       undefined, // function(uri: string): Promise {}
   1110   // options to modify validated data:
   1111   removeAdditional: false,
   1112   useDefaults:      false,
   1113   coerceTypes:      false,
   1114   // strict mode options
   1115   strictDefaults:   false,
   1116   strictKeywords:   false,
   1117   // asynchronous validation options:
   1118   transpile:        undefined, // requires ajv-async package
   1119   // advanced options:
   1120   meta:             true,
   1121   validateSchema:   true,
   1122   addUsedSchema:    true,
   1123   inlineRefs:       true,
   1124   passContext:      false,
   1125   loopRequired:     Infinity,
   1126   ownProperties:    false,
   1127   multipleOfPrecision: false,
   1128   errorDataPath:    'object', // deprecated
   1129   messages:         true,
   1130   sourceCode:       false,
   1131   processCode:      undefined, // function (str: string): string {}
   1132   cache:            new Cache,
   1133   serialize:        undefined
   1134 }
   1135 ```
   1136 
   1137 ##### Validation and reporting options
   1138 
   1139 - _$data_: support [$data references](#data-reference). Draft 6 meta-schema that is added by default will be extended to allow them. If you want to use another meta-schema you need to use $dataMetaSchema method to add support for $data reference. See [API](#api).
   1140 - _allErrors_: check all rules collecting all errors. Default is to return after the first error.
   1141 - _verbose_: include the reference to the part of the schema (`schema` and `parentSchema`) and validated data in errors (false by default).
   1142 - _$comment_ (NEW in Ajv version 6.0): log or pass the value of `$comment` keyword to a function. Option values:
   1143   - `false` (default): ignore $comment keyword.
   1144   - `true`: log the keyword value to console.
   1145   - function: pass the keyword value, its schema path and root schema to the specified function
   1146 - _jsonPointers_: set `dataPath` property of errors using [JSON Pointers](https://tools.ietf.org/html/rfc6901) instead of JavaScript property access notation.
   1147 - _uniqueItems_: validate `uniqueItems` keyword (true by default).
   1148 - _unicode_: calculate correct length of strings with unicode pairs (true by default). Pass `false` to use `.length` of strings that is faster, but gives "incorrect" lengths of strings with unicode pairs - each unicode pair is counted as two characters.
   1149 - _nullable_: support keyword "nullable" from [Open API 3 specification](https://swagger.io/docs/specification/data-models/data-types/).
   1150 - _format_: formats validation mode. Option values:
   1151   - `"fast"` (default) - simplified and fast validation (see [Formats](#formats) for details of which formats are available and affected by this option).
   1152   - `"full"` - more restrictive and slow validation. E.g., 25:00:00 and 2015/14/33 will be invalid time and date in 'full' mode but it will be valid in 'fast' mode.
   1153   - `false` - ignore all format keywords.
   1154 - _formats_: an object with custom formats. Keys and values will be passed to `addFormat` method.
   1155 - _keywords_: an object with custom keywords. Keys and values will be passed to `addKeyword` method.
   1156 - _unknownFormats_: handling of unknown formats. Option values:
   1157   - `true` (default) - if an unknown format is encountered the exception is thrown during schema compilation. If `format` keyword value is [$data reference](#data-reference) and it is unknown the validation will fail.
   1158   - `[String]` - an array of unknown format names that will be ignored. This option can be used to allow usage of third party schemas with format(s) for which you don't have definitions, but still fail if another unknown format is used. If `format` keyword value is [$data reference](#data-reference) and it is not in this array the validation will fail.
   1159   - `"ignore"` - to log warning during schema compilation and always pass validation (the default behaviour in versions before 5.0.0). This option is not recommended, as it allows to mistype format name and it won't be validated without any error message. This behaviour is required by JSON Schema specification.
   1160 - _schemas_: an array or object of schemas that will be added to the instance. In case you pass the array the schemas must have IDs in them. When the object is passed the method `addSchema(value, key)` will be called for each schema in this object.
   1161 - _logger_: sets the logging method. Default is the global `console` object that should have methods `log`, `warn` and `error`. See [Error logging](#error-logging). Option values:
   1162   - custom logger - it should have methods `log`, `warn` and `error`. If any of these methods is missing an exception will be thrown.
   1163   - `false` - logging is disabled.
   1164 
   1165 
   1166 ##### Referenced schema options
   1167 
   1168 - _schemaId_: this option defines which keywords are used as schema URI. Option value:
   1169   - `"$id"` (default) - only use `$id` keyword as schema URI (as specified in JSON Schema draft-06/07), ignore `id` keyword (if it is present a warning will be logged).
   1170   - `"id"` - only use `id` keyword as schema URI (as specified in JSON Schema draft-04), ignore `$id` keyword (if it is present a warning will be logged).
   1171   - `"auto"` - use both `$id` and `id` keywords as schema URI. If both are present (in the same schema object) and different the exception will be thrown during schema compilation.
   1172 - _missingRefs_: handling of missing referenced schemas. Option values:
   1173   - `true` (default) - if the reference cannot be resolved during compilation the exception is thrown. The thrown error has properties `missingRef` (with hash fragment) and `missingSchema` (without it). Both properties are resolved relative to the current base id (usually schema id, unless it was substituted).
   1174   - `"ignore"` - to log error during compilation and always pass validation.
   1175   - `"fail"` - to log error and successfully compile schema but fail validation if this rule is checked.
   1176 - _extendRefs_: validation of other keywords when `$ref` is present in the schema. Option values:
   1177   - `"ignore"` (default) - when `$ref` is used other keywords are ignored (as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3) standard). A warning will be logged during the schema compilation.
   1178   - `"fail"` (recommended) - if other validation keywords are used together with `$ref` the exception will be thrown when the schema is compiled. This option is recommended to make sure schema has no keywords that are ignored, which can be confusing.
   1179   - `true` - validate all keywords in the schemas with `$ref` (the default behaviour in versions before 5.0.0).
   1180 - _loadSchema_: asynchronous function that will be used to load remote schemas when `compileAsync` [method](#api-compileAsync) is used and some reference is missing (option `missingRefs` should NOT be 'fail' or 'ignore'). This function should accept remote schema uri as a parameter and return a Promise that resolves to a schema. See example in [Asynchronous compilation](#asynchronous-schema-compilation).
   1181 
   1182 
   1183 ##### Options to modify validated data
   1184 
   1185 - _removeAdditional_: remove additional properties - see example in [Filtering data](#filtering-data). This option is not used if schema is added with `addMetaSchema` method. Option values:
   1186   - `false` (default) - not to remove additional properties
   1187   - `"all"` - all additional properties are removed, regardless of `additionalProperties` keyword in schema (and no validation is made for them).
   1188   - `true` - only additional properties with `additionalProperties` keyword equal to `false` are removed.
   1189   - `"failing"` - additional properties that fail schema validation will be removed (where `additionalProperties` keyword is `false` or schema).
   1190 - _useDefaults_: replace missing or undefined properties and items with the values from corresponding `default` keywords. Default behaviour is to ignore `default` keywords. This option is not used if schema is added with `addMetaSchema` method. See examples in [Assigning defaults](#assigning-defaults). Option values:
   1191   - `false` (default) - do not use defaults
   1192   - `true` - insert defaults by value (object literal is used).
   1193   - `"empty"` - in addition to missing or undefined, use defaults for properties and items that are equal to `null` or `""` (an empty string).
   1194   - `"shared"` (deprecated) - insert defaults by reference. If the default is an object, it will be shared by all instances of validated data. If you modify the inserted default in the validated data, it will be modified in the schema as well.
   1195 - _coerceTypes_: change data type of data to match `type` keyword. See the example in [Coercing data types](#coercing-data-types) and [coercion rules](https://github.com/epoberezkin/ajv/blob/master/COERCION.md). Option values:
   1196   - `false` (default) - no type coercion.
   1197   - `true` - coerce scalar data types.
   1198   - `"array"` - in addition to coercions between scalar types, coerce scalar data to an array with one element and vice versa (as required by the schema).
   1199 
   1200 
   1201 ##### Strict mode options
   1202 
   1203 - _strictDefaults_: report ignored `default` keywords in schemas. Option values:
   1204   - `false` (default) - ignored defaults are not reported
   1205   - `true` - if an ignored default is present, throw an error
   1206   - `"log"` - if an ignored default is present, log warning
   1207 - _strictKeywords_: report unknown keywords in schemas. Option values:
   1208   - `false` (default) - unknown keywords are not reported
   1209   - `true` - if an unknown keyword is present, throw an error
   1210   - `"log"` - if an unknown keyword is present, log warning
   1211 
   1212 
   1213 ##### Asynchronous validation options
   1214 
   1215 - _transpile_: Requires [ajv-async](https://github.com/epoberezkin/ajv-async) package. It determines whether Ajv transpiles compiled asynchronous validation function. Option values:
   1216   - `undefined` (default) - transpile with [nodent](https://github.com/MatAtBread/nodent) if async functions are not supported.
   1217   - `true` - always transpile with nodent.
   1218   - `false` - do not transpile; if async functions are not supported an exception will be thrown.
   1219 
   1220 
   1221 ##### Advanced options
   1222 
   1223 - _meta_: add [meta-schema](http://json-schema.org/documentation.html) so it can be used by other schemas (true by default). If an object is passed, it will be used as the default meta-schema for schemas that have no `$schema` keyword. This default meta-schema MUST have `$schema` keyword.
   1224 - _validateSchema_: validate added/compiled schemas against meta-schema (true by default). `$schema` property in the schema can be http://json-schema.org/draft-07/schema or absent (draft-07 meta-schema will be used) or can be a reference to the schema previously added with `addMetaSchema` method. Option values:
   1225   - `true` (default) -  if the validation fails, throw the exception.
   1226   - `"log"` - if the validation fails, log error.
   1227   - `false` - skip schema validation.
   1228 - _addUsedSchema_: by default methods `compile` and `validate` add schemas to the instance if they have `$id` (or `id`) property that doesn't start with "#". If `$id` is present and it is not unique the exception will be thrown. Set this option to `false` to skip adding schemas to the instance and the `$id` uniqueness check when these methods are used. This option does not affect `addSchema` method.
   1229 - _inlineRefs_: Affects compilation of referenced schemas. Option values:
   1230   - `true` (default) - the referenced schemas that don't have refs in them are inlined, regardless of their size - that substantially improves performance at the cost of the bigger size of compiled schema functions.
   1231   - `false` - to not inline referenced schemas (they will be compiled as separate functions).
   1232   - integer number - to limit the maximum number of keywords of the schema that will be inlined.
   1233 - _passContext_: pass validation context to custom keyword functions. If this option is `true` and you pass some context to the compiled validation function with `validate.call(context, data)`, the `context` will be available as `this` in your custom keywords. By default `this` is Ajv instance.
   1234 - _loopRequired_: by default `required` keyword is compiled into a single expression (or a sequence of statements in `allErrors` mode). In case of a very large number of properties in this keyword it may result in a very big validation function. Pass integer to set the number of properties above which `required` keyword will be validated in a loop - smaller validation function size but also worse performance.
   1235 - _ownProperties_: by default Ajv iterates over all enumerable object properties; when this option is `true` only own enumerable object properties (i.e. found directly on the object rather than on its prototype) are iterated. Contributed by @mbroadst.
   1236 - _multipleOfPrecision_: by default `multipleOf` keyword is validated by comparing the result of division with parseInt() of that result. It works for dividers that are bigger than 1. For small dividers such as 0.01 the result of the division is usually not integer (even when it should be integer, see issue [#84](https://github.com/epoberezkin/ajv/issues/84)). If you need to use fractional dividers set this option to some positive integer N to have `multipleOf` validated using this formula: `Math.abs(Math.round(division) - division) < 1e-N` (it is slower but allows for float arithmetics deviations).
   1237 - _errorDataPath_ (deprecated): set `dataPath` to point to 'object' (default) or to 'property' when validating keywords `required`, `additionalProperties` and `dependencies`.
   1238 - _messages_: Include human-readable messages in errors. `true` by default. `false` can be passed when custom messages are used (e.g. with [ajv-i18n](https://github.com/epoberezkin/ajv-i18n)).
   1239 - _sourceCode_: add `sourceCode` property to validating function (for debugging; this code can be different from the result of toString call).
   1240 - _processCode_: an optional function to process generated code before it is passed to Function constructor. It can be used to either beautify (the validating function is generated without line-breaks) or to transpile code. Starting from version 5.0.0 this option replaced options:
   1241   - `beautify` that formatted the generated function using [js-beautify](https://github.com/beautify-web/js-beautify). If you want to beautify the generated code pass `require('js-beautify').js_beautify`.
   1242   - `transpile` that transpiled asynchronous validation function. You can still use `transpile` option with [ajv-async](https://github.com/epoberezkin/ajv-async) package. See [Asynchronous validation](#asynchronous-validation) for more information.
   1243 - _cache_: an optional instance of cache to store compiled schemas using stable-stringified schema as a key. For example, set-associative cache [sacjs](https://github.com/epoberezkin/sacjs) can be used. If not passed then a simple hash is used which is good enough for the common use case (a limited number of statically defined schemas). Cache should have methods `put(key, value)`, `get(key)`, `del(key)` and `clear()`.
   1244 - _serialize_: an optional function to serialize schema to cache key. Pass `false` to use schema itself as a key (e.g., if WeakMap used as a cache). By default [fast-json-stable-stringify](https://github.com/epoberezkin/fast-json-stable-stringify) is used.
   1245 
   1246 
   1247 ## Validation errors
   1248 
   1249 In case of validation failure, Ajv assigns the array of errors to `errors` property of validation function (or to `errors` property of Ajv instance when `validate` or `validateSchema` methods were called). In case of [asynchronous validation](#asynchronous-validation), the returned promise is rejected with exception `Ajv.ValidationError` that has `errors` property.
   1250 
   1251 
   1252 ### Error objects
   1253 
   1254 Each error is an object with the following properties:
   1255 
   1256 - _keyword_: validation keyword.
   1257 - _dataPath_: the path to the part of the data that was validated. By default `dataPath` uses JavaScript property access notation (e.g., `".prop[1].subProp"`). When the option `jsonPointers` is true (see [Options](#options)) `dataPath` will be set using JSON pointer standard (e.g., `"/prop/1/subProp"`).
   1258 - _schemaPath_: the path (JSON-pointer as a URI fragment) to the schema of the keyword that failed validation.
   1259 - _params_: the object with the additional information about error that can be used to create custom error messages (e.g., using [ajv-i18n](https://github.com/epoberezkin/ajv-i18n) package). See below for parameters set by all keywords.
   1260 - _message_: the standard error message (can be excluded with option `messages` set to false).
   1261 - _schema_: the schema of the keyword (added with `verbose` option).
   1262 - _parentSchema_: the schema containing the keyword (added with `verbose` option)
   1263 - _data_: the data validated by the keyword (added with `verbose` option).
   1264 
   1265 __Please note__: `propertyNames` keyword schema validation errors have an additional property `propertyName`, `dataPath` points to the object. After schema validation for each property name, if it is invalid an additional error is added with the property `keyword` equal to `"propertyNames"`.
   1266 
   1267 
   1268 ### Error parameters
   1269 
   1270 Properties of `params` object in errors depend on the keyword that failed validation.
   1271 
   1272 - `maxItems`, `minItems`, `maxLength`, `minLength`, `maxProperties`, `minProperties` - property `limit` (number, the schema of the keyword).
   1273 - `additionalItems` - property `limit` (the maximum number of allowed items in case when `items` keyword is an array of schemas and `additionalItems` is false).
   1274 - `additionalProperties` - property `additionalProperty` (the property not used in `properties` and `patternProperties` keywords).
   1275 - `dependencies` - properties:
   1276   - `property` (dependent property),
   1277   - `missingProperty` (required missing dependency - only the first one is reported currently)
   1278   - `deps` (required dependencies, comma separated list as a string),
   1279   - `depsCount` (the number of required dependencies).
   1280 - `format` - property `format` (the schema of the keyword).
   1281 - `maximum`, `minimum` - properties:
   1282   - `limit` (number, the schema of the keyword),
   1283   - `exclusive` (boolean, the schema of `exclusiveMaximum` or `exclusiveMinimum`),
   1284   - `comparison` (string, comparison operation to compare the data to the limit, with the data on the left and the limit on the right; can be "<", "<=", ">", ">=")
   1285 - `multipleOf` - property `multipleOf` (the schema of the keyword)
   1286 - `pattern` - property `pattern` (the schema of the keyword)
   1287 - `required` - property `missingProperty` (required property that is missing).
   1288 - `propertyNames` - property `propertyName` (an invalid property name).
   1289 - `patternRequired` (in ajv-keywords) - property `missingPattern` (required pattern that did not match any property).
   1290 - `type` - property `type` (required type(s), a string, can be a comma-separated list)
   1291 - `uniqueItems` - properties `i` and `j` (indices of duplicate items).
   1292 - `const` - property `allowedValue` pointing to the value (the schema of the keyword).
   1293 - `enum` - property `allowedValues` pointing to the array of values (the schema of the keyword).
   1294 - `$ref` - property `ref` with the referenced schema URI.
   1295 - `oneOf` - property `passingSchemas` (array of indices of passing schemas, null if no schema passes).
   1296 - custom keywords (in case keyword definition doesn't create errors) - property `keyword` (the keyword name).
   1297 
   1298 
   1299 ### Error logging
   1300 
   1301 Using the `logger` option when initiallizing Ajv will allow you to define custom logging. Here you can build upon the exisiting logging. The use of other logging packages is supported as long as the package or its associated wrapper exposes the required methods. If any of the required methods are missing an exception will be thrown.
   1302 - **Required Methods**: `log`, `warn`, `error`
   1303 
   1304 ```javascript
   1305 var otherLogger = new OtherLogger();
   1306 var ajv = new Ajv({
   1307   logger: {
   1308     log: console.log.bind(console),
   1309     warn: function warn() {
   1310       otherLogger.logWarn.apply(otherLogger, arguments);
   1311     },
   1312     error: function error() {
   1313       otherLogger.logError.apply(otherLogger, arguments);
   1314       console.error.apply(console, arguments);
   1315     }
   1316   }
   1317 });
   1318 ```
   1319 
   1320 
   1321 ## Plugins
   1322 
   1323 Ajv can be extended with plugins that add custom keywords, formats or functions to process generated code. When such plugin is published as npm package it is recommended that it follows these conventions:
   1324 
   1325 - it exports a function
   1326 - this function accepts ajv instance as the first parameter and returns the same instance to allow chaining
   1327 - this function can accept an optional configuration as the second parameter
   1328 
   1329 If you have published a useful plugin please submit a PR to add it to the next section.
   1330 
   1331 
   1332 ## Related packages
   1333 
   1334 - [ajv-async](https://github.com/epoberezkin/ajv-async) - plugin to configure async validation mode
   1335 - [ajv-bsontype](https://github.com/BoLaMN/ajv-bsontype) - plugin to validate mongodb's bsonType formats
   1336 - [ajv-cli](https://github.com/jessedc/ajv-cli) - command line interface
   1337 - [ajv-errors](https://github.com/epoberezkin/ajv-errors) - plugin for custom error messages
   1338 - [ajv-i18n](https://github.com/epoberezkin/ajv-i18n) - internationalised error messages
   1339 - [ajv-istanbul](https://github.com/epoberezkin/ajv-istanbul) - plugin to instrument generated validation code to measure test coverage of your schemas
   1340 - [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) - plugin with custom validation keywords (select, typeof, etc.)
   1341 - [ajv-merge-patch](https://github.com/epoberezkin/ajv-merge-patch) - plugin with keywords $merge and $patch
   1342 - [ajv-pack](https://github.com/epoberezkin/ajv-pack) - produces a compact module exporting validation functions
   1343 
   1344 
   1345 ## Some packages using Ajv
   1346 
   1347 - [webpack](https://github.com/webpack/webpack) - a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser
   1348 - [jsonscript-js](https://github.com/JSONScript/jsonscript-js) - the interpreter for [JSONScript](http://www.jsonscript.org) - scripted processing of existing endpoints and services
   1349 - [osprey-method-handler](https://github.com/mulesoft-labs/osprey-method-handler) - Express middleware for validating requests and responses based on a RAML method object, used in [osprey](https://github.com/mulesoft/osprey) - validating API proxy generated from a RAML definition
   1350 - [har-validator](https://github.com/ahmadnassri/har-validator) - HTTP Archive (HAR) validator
   1351 - [jsoneditor](https://github.com/josdejong/jsoneditor) - a web-based tool to view, edit, format, and validate JSON http://jsoneditoronline.org
   1352 - [JSON Schema Lint](https://github.com/nickcmaynard/jsonschemalint) - a web tool to validate JSON/YAML document against a single JSON Schema http://jsonschemalint.com
   1353 - [objection](https://github.com/vincit/objection.js) - SQL-friendly ORM for Node.js
   1354 - [table](https://github.com/gajus/table) - formats data into a string table
   1355 - [ripple-lib](https://github.com/ripple/ripple-lib) - a JavaScript API for interacting with [Ripple](https://ripple.com) in Node.js and the browser
   1356 - [restbase](https://github.com/wikimedia/restbase) - distributed storage with REST API & dispatcher for backend services built to provide a low-latency & high-throughput API for Wikipedia / Wikimedia content
   1357 - [hippie-swagger](https://github.com/CacheControl/hippie-swagger) - [Hippie](https://github.com/vesln/hippie) wrapper that provides end to end API testing with swagger validation
   1358 - [react-form-controlled](https://github.com/seeden/react-form-controlled) - React controlled form components with validation
   1359 - [rabbitmq-schema](https://github.com/tjmehta/rabbitmq-schema) - a schema definition module for RabbitMQ graphs and messages
   1360 - [@query/schema](https://www.npmjs.com/package/@query/schema) - stream filtering with a URI-safe query syntax parsing to JSON Schema
   1361 - [chai-ajv-json-schema](https://github.com/peon374/chai-ajv-json-schema) - chai plugin to us JSON Schema with expect in mocha tests
   1362 - [grunt-jsonschema-ajv](https://github.com/SignpostMarv/grunt-jsonschema-ajv) - Grunt plugin for validating files against JSON Schema
   1363 - [extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) - extract text from bundle into a file
   1364 - [electron-builder](https://github.com/electron-userland/electron-builder) - a solution to package and build a ready for distribution Electron app
   1365 - [addons-linter](https://github.com/mozilla/addons-linter) - Mozilla Add-ons Linter
   1366 - [gh-pages-generator](https://github.com/epoberezkin/gh-pages-generator) - multi-page site generator converting markdown files to GitHub pages
   1367 - [ESLint](https://github.com/eslint/eslint) - the pluggable linting utility for JavaScript and JSX
   1368 
   1369 
   1370 ## Tests
   1371 
   1372 ```
   1373 npm install
   1374 git submodule update --init
   1375 npm test
   1376 ```
   1377 
   1378 ## Contributing
   1379 
   1380 All validation functions are generated using doT templates in [dot](https://github.com/epoberezkin/ajv/tree/master/lib/dot) folder. Templates are precompiled so doT is not a run-time dependency.
   1381 
   1382 `npm run build` - compiles templates to [dotjs](https://github.com/epoberezkin/ajv/tree/master/lib/dotjs) folder.
   1383 
   1384 `npm run watch` - automatically compiles templates when files in dot folder change
   1385 
   1386 Please see [Contributing guidelines](https://github.com/epoberezkin/ajv/blob/master/CONTRIBUTING.md)
   1387 
   1388 
   1389 ## Changes history
   1390 
   1391 See https://github.com/epoberezkin/ajv/releases
   1392 
   1393 __Please note__: [Changes in version 6.0.0](https://github.com/epoberezkin/ajv/releases/tag/v6.0.0).
   1394 
   1395 [Version 5.0.0](https://github.com/epoberezkin/ajv/releases/tag/5.0.0).
   1396 
   1397 [Version 4.0.0](https://github.com/epoberezkin/ajv/releases/tag/4.0.0).
   1398 
   1399 [Version 3.0.0](https://github.com/epoberezkin/ajv/releases/tag/3.0.0).
   1400 
   1401 [Version 2.0.0](https://github.com/epoberezkin/ajv/releases/tag/2.0.0).
   1402 
   1403 
   1404 ## Open-source software support
   1405 
   1406 Ajv is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.
   1407 
   1408 
   1409 ## License
   1410 
   1411 [MIT](https://github.com/epoberezkin/ajv/blob/master/LICENSE)