basant307/AI_Governance_Project
048
1<img align="right" alt="Ajv logo" width="160" src="https://ajv.js.org/images/ajv_logo.png">2 3# Ajv: Another JSON Schema Validator4 5The fastest JSON Schema validator for Node.js and browser. Supports draft-04/06/07.6 7[](https://travis-ci.org/ajv-validator/ajv)8[](https://www.npmjs.com/package/ajv)9[](https://www.npmjs.com/package/ajv/v/7.0.0-beta.0)10[](https://www.npmjs.com/package/ajv)11[](https://coveralls.io/github/ajv-validator/ajv?branch=master)12[](https://gitter.im/ajv-validator/ajv)13[](https://github.com/sponsors/epoberezkin)14 15 16## Ajv v7 beta is released17 18[Ajv version 7.0.0-beta.0](https://github.com/ajv-validator/ajv/tree/v7-beta) is released with these changes:19 20- to reduce the mistakes in JSON schemas and unexpected validation results, [strict mode](./docs/strict-mode.md) is added - it prohibits ignored or ambiguous JSON Schema elements.21- to make code injection from untrusted schemas impossible, [code generation](./docs/codegen.md) is fully re-written to be safe.22- to simplify Ajv extensions, the new keyword API that is used by pre-defined keywords is available to user-defined keywords - it is much easier to define any keywords now, especially with subschemas.23- schemas are compiled to ES6 code (ES5 code generation is supported with an option).24- to improve reliability and maintainability the code is migrated to TypeScript.25 26**Please note**:27 28- the support for JSON-Schema draft-04 is removed - if you have schemas using "id" attributes you have to replace them with "\$id" (or continue using version 6 that will be supported until 02/28/2021).29- all formats are separated to ajv-formats package - they have to be explicitely added if you use them.30 31See [release notes](https://github.com/ajv-validator/ajv/releases/tag/v7.0.0-beta.0) for the details.32 33To install the new version:34 35```bash36npm install ajv@beta37```38 39See [Getting started with v7](https://github.com/ajv-validator/ajv/tree/v7-beta#usage) for code example.40 41 42## Mozilla MOSS grant and OpenJS Foundation43 44[<img src="https://www.poberezkin.com/images/mozilla.png" width="240" height="68">](https://www.mozilla.org/en-US/moss/) [<img src="https://www.poberezkin.com/images/openjs.png" width="220" height="68">](https://openjsf.org/blog/2020/08/14/ajv-joins-openjs-foundation-as-an-incubation-project/)45 46Ajv has been awarded a grant from Mozilla’s [Open Source Support (MOSS) program](https://www.mozilla.org/en-US/moss/) in the “Foundational Technology” track! It will sponsor the development of Ajv support of [JSON Schema version 2019-09](https://tools.ietf.org/html/draft-handrews-json-schema-02) and of [JSON Type Definition](https://tools.ietf.org/html/draft-ucarion-json-type-definition-04).47 48Ajv also joined [OpenJS Foundation](https://openjsf.org/) – having this support will help ensure the longevity and stability of Ajv for all its users.49 50This [blog post](https://www.poberezkin.com/posts/2020-08-14-ajv-json-validator-mozilla-open-source-grant-openjs-foundation.html) has more details.51 52I am looking for the long term maintainers of Ajv – working with [ReadySet](https://www.thereadyset.co/), also sponsored by Mozilla, to establish clear guidelines for the role of a "maintainer" and the contribution standards, and to encourage a wider, more inclusive, contribution from the community.53 54 55## Please [sponsor Ajv development](https://github.com/sponsors/epoberezkin)56 57Since I asked to support Ajv development 40 people and 6 organizations contributed via GitHub and OpenCollective - this support helped receiving the MOSS grant!58 59Your continuing support is very important - the funds will be used to develop and maintain Ajv once the next major version is released.60 61Please sponsor Ajv via:62- [GitHub sponsors page](https://github.com/sponsors/epoberezkin) (GitHub will match it)63- [Ajv Open Collective️](https://opencollective.com/ajv)64 65Thank you.66 67 68#### Open Collective sponsors69 70<a href="https://opencollective.com/ajv"><img src="https://opencollective.com/ajv/individuals.svg?width=890"></a>71 72<a href="https://opencollective.com/ajv/organization/0/website"><img src="https://opencollective.com/ajv/organization/0/avatar.svg"></a>73<a href="https://opencollective.com/ajv/organization/1/website"><img src="https://opencollective.com/ajv/organization/1/avatar.svg"></a>74<a href="https://opencollective.com/ajv/organization/2/website"><img src="https://opencollective.com/ajv/organization/2/avatar.svg"></a>75<a href="https://opencollective.com/ajv/organization/3/website"><img src="https://opencollective.com/ajv/organization/3/avatar.svg"></a>76<a href="https://opencollective.com/ajv/organization/4/website"><img src="https://opencollective.com/ajv/organization/4/avatar.svg"></a>77<a href="https://opencollective.com/ajv/organization/5/website"><img src="https://opencollective.com/ajv/organization/5/avatar.svg"></a>78<a href="https://opencollective.com/ajv/organization/6/website"><img src="https://opencollective.com/ajv/organization/6/avatar.svg"></a>79<a href="https://opencollective.com/ajv/organization/7/website"><img src="https://opencollective.com/ajv/organization/7/avatar.svg"></a>80<a href="https://opencollective.com/ajv/organization/8/website"><img src="https://opencollective.com/ajv/organization/8/avatar.svg"></a>81<a href="https://opencollective.com/ajv/organization/9/website"><img src="https://opencollective.com/ajv/organization/9/avatar.svg"></a>82 83 84## Using version 685 86[JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) is published.87 88[Ajv version 6.0.0](https://github.com/ajv-validator/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).89 90__Please note__: To use Ajv with draft-06 schemas you need to explicitly add the meta-schema to the validator instance:91 92```javascript93ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-06.json'));94```95 96To use Ajv with draft-04 schemas in addition to explicitly adding meta-schema you also need to use option schemaId:97 98```javascript99var ajv = new Ajv({schemaId: 'id'});100// If you want to use both draft-04 and draft-06/07 schemas:101// var ajv = new Ajv({schemaId: 'auto'});102ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));103```104 105 106## Contents107 108- [Performance](#performance)109- [Features](#features)110- [Getting started](#getting-started)111- [Frequently Asked Questions](https://github.com/ajv-validator/ajv/blob/master/FAQ.md)112- [Using in browser](#using-in-browser)113 - [Ajv and Content Security Policies (CSP)](#ajv-and-content-security-policies-csp)114- [Command line interface](#command-line-interface)115- Validation116 - [Keywords](#validation-keywords)117 - [Annotation keywords](#annotation-keywords)118 - [Formats](#formats)119 - [Combining schemas with $ref](#ref)120 - [$data reference](#data-reference)121 - NEW: [$merge and $patch keywords](#merge-and-patch-keywords)122 - [Defining custom keywords](#defining-custom-keywords)123 - [Asynchronous schema compilation](#asynchronous-schema-compilation)124 - [Asynchronous validation](#asynchronous-validation)125- [Security considerations](#security-considerations)126 - [Security contact](#security-contact)127 - [Untrusted schemas](#untrusted-schemas)128 - [Circular references in objects](#circular-references-in-javascript-objects)129 - [Trusted schemas](#security-risks-of-trusted-schemas)130 - [ReDoS attack](#redos-attack)131- Modifying data during validation132 - [Filtering data](#filtering-data)133 - [Assigning defaults](#assigning-defaults)134 - [Coercing data types](#coercing-data-types)135- API136 - [Methods](#api)137 - [Options](#options)138 - [Validation errors](#validation-errors)139- [Plugins](#plugins)140- [Related packages](#related-packages)141- [Some packages using Ajv](#some-packages-using-ajv)142- [Tests, Contributing, Changes history](#tests)143- [Support, Code of conduct, License](#open-source-software-support)144 145 146## Performance147 148Ajv 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.149 150Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:151 152- [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark) - 50% faster than the second place153- [jsck benchmark](https://github.com/pandastrike/jsck#benchmarks) - 20-190% faster154- [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)155- [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)156 157 158Performance of different validators by [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark):159 160[](https://github.com/ebdrup/json-schema-benchmark/blob/master/README.md#performance)161 162 163## Features164 165- Ajv implements full JSON Schema [draft-06/07](http://json-schema.org/) and draft-04 standards:166 - all validation keywords (see [JSON Schema validation keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md))167 - full support of remote refs (remote schemas have to be added with `addSchema` or compiled to be available)168 - support of circular references between schemas169 - correct string lengths for strings with unicode pairs (can be turned off)170 - [formats](#formats) defined by JSON Schema draft-07 standard and custom formats (can be turned off)171 - [validates schemas against meta-schema](#api-validateschema)172- supports [browsers](#using-in-browser) and Node.js 0.10-14.x173- [asynchronous loading](#asynchronous-schema-compilation) of referenced schemas during compilation174- "All errors" validation mode with [option allErrors](#options)175- [error messages with parameters](#validation-errors) describing error reasons to allow creating custom error messages176- i18n error messages support with [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) package177- [filtering data](#filtering-data) from additional properties178- [assigning defaults](#assigning-defaults) to missing properties and items179- [coercing data](#coercing-data-types) to the types specified in `type` keywords180- [custom keywords](#defining-custom-keywords)181- draft-06/07 keywords `const`, `contains`, `propertyNames` and `if/then/else`182- draft-06 boolean schemas (`true`/`false` as a schema to always pass/fail).183- 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/ajv-validator/ajv-keywords) package184- [$data reference](#data-reference) to use values from the validated data as values for the schema keywords185- [asynchronous validation](#asynchronous-validation) of custom formats and keywords186 187 188## Install189 190```191npm install ajv192```193 194 195## <a name="usage"></a>Getting started196 197Try it in the Node.js REPL: https://tonicdev.com/npm/ajv198 199 200The fastest validation call:201 202```javascript203// Node.js require:204var Ajv = require('ajv');205// or ESM/TypeScript import206import Ajv from 'ajv';207 208var ajv = new Ajv(); // options can be passed, e.g. {allErrors: true}209var validate = ajv.compile(schema);210var valid = validate(data);211if (!valid) console.log(validate.errors);212```213 214or with less code215 216```javascript217// ...218var valid = ajv.validate(schema, data);219if (!valid) console.log(ajv.errors);220// ...221```222 223or224 225```javascript226// ...227var valid = ajv.addSchema(schema, 'mySchema')228 .validate('mySchema', data);229if (!valid) console.log(ajv.errorsText());230// ...231```232 233See [API](#api) and [Options](#options) for more details.234 235Ajv 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.236 237The best performance is achieved when using compiled functions returned by `compile` or `getSchema` methods (there is no additional function call).238 239__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)240 241__Note for TypeScript users__: `ajv` provides its own TypeScript declarations242out of the box, so you don't need to install the deprecated `@types/ajv`243module.244 245 246## Using in browser247 248You can require Ajv directly from the code you browserify - in this case Ajv will be a part of your bundle.249 250If 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)).251 252Then you need to load Ajv in the browser:253```html254<script src="ajv.min.js"></script>255```256 257This bundle can be used with different module systems; it creates global `Ajv` if no module system is found.258 259The browser bundle is available on [cdnjs](https://cdnjs.com/libraries/ajv).260 261Ajv is tested with these browsers:262 263[](https://saucelabs.com/u/epoberezkin)264 265__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/ajv-validator/ajv/issues/234)).266 267 268### Ajv and Content Security Policies (CSP)269 270If you're using Ajv to compile a schema (the typical use) in a browser document that is loaded with a Content Security Policy (CSP), that policy will require a `script-src` directive that includes the value `'unsafe-eval'`.271:warning: NOTE, however, that `unsafe-eval` is NOT recommended in a secure CSP[[1]](https://developer.chrome.com/extensions/contentSecurityPolicy#relaxing-eval), as it has the potential to open the document to cross-site scripting (XSS) attacks.272 273In order to make use of Ajv without easing your CSP, you can [pre-compile a schema using the CLI](https://github.com/ajv-validator/ajv-cli#compile-schemas). This will transpile the schema JSON into a JavaScript file that exports a `validate` function that works simlarly to a schema compiled at runtime.274 275Note that pre-compilation of schemas is performed using [ajv-pack](https://github.com/ajv-validator/ajv-pack) and there are [some limitations to the schema features it can compile](https://github.com/ajv-validator/ajv-pack#limitations). A successfully pre-compiled schema is equivalent to the same schema compiled at runtime.276 277 278## Command line interface279 280CLI is available as a separate npm package [ajv-cli](https://github.com/ajv-validator/ajv-cli). It supports:281 282- compiling JSON Schemas to test their validity283- BETA: generating standalone module exporting a validation function to be used without Ajv (using [ajv-pack](https://github.com/ajv-validator/ajv-pack))284- migrate schemas to draft-07 (using [json-schema-migrate](https://github.com/epoberezkin/json-schema-migrate))285- validating data file(s) against JSON Schema286- testing expected validity of data against JSON Schema287- referenced schemas288- custom meta-schemas289- files in JSON, JSON5, YAML, and JavaScript format290- all Ajv options291- reporting changes in data after validation in [JSON-patch](https://tools.ietf.org/html/rfc6902) format292 293 294## Validation keywords295 296Ajv supports all validation keywords from draft-07 of JSON Schema standard:297 298- [type](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#type)299- [for numbers](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-numbers) - maximum, minimum, exclusiveMaximum, exclusiveMinimum, multipleOf300- [for strings](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-strings) - maxLength, minLength, pattern, format301- [for arrays](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-arrays) - maxItems, minItems, uniqueItems, items, additionalItems, [contains](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#contains)302- [for objects](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-objects) - maxProperties, minProperties, required, properties, patternProperties, additionalProperties, dependencies, [propertyNames](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#propertynames)303- [for all types](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-all-types) - enum, [const](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#const)304- [compound keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#compound-keywords) - not, oneOf, anyOf, allOf, [if/then/else](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#ifthenelse)305 306With [ajv-keywords](https://github.com/ajv-validator/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:307 308- [patternRequired](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#patternrequired-proposed) - like `required` but with patterns that some property should match.309- [formatMaximum, formatMinimum, formatExclusiveMaximum, formatExclusiveMinimum](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#formatmaximum--formatminimum-and-exclusiveformatmaximum--exclusiveformatminimum-proposed) - setting limits for date, time, etc.310 311See [JSON Schema validation keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md) for more details.312 313 314## Annotation keywords315 316JSON Schema specification defines several annotation keywords that describe schema itself but do not perform any validation.317 318- `title` and `description`: information about the data represented by that schema319- `$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).320- `default`: a default value of the data instance, see [Assigning defaults](#assigning-defaults).321- `examples` (NEW in draft-06): an array of data instances. Ajv does not check the validity of these instances against the schema.322- `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.).323- `contentEncoding`: [RFC 2045](https://tools.ietf.org/html/rfc2045#section-6.1 ), e.g., "base64".324- `contentMediaType`: [RFC 2046](https://tools.ietf.org/html/rfc2046), e.g., "image/png".325 326__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.327 328 329## Formats330 331Ajv 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).332 333__Please note__: if you need to use "format" keyword to validate untrusted data, you MUST assess their suitability and safety for your validation scenarios.334 335The following formats are implemented for string validation with "format" keyword:336 337- _date_: full-date according to [RFC3339](http://tools.ietf.org/html/rfc3339#section-5.6).338- _time_: time with optional time-zone.339- _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)).340- _uri_: full URI.341- _uri-reference_: URI reference, including full and relative URIs.342- _uri-template_: URI template according to [RFC6570](https://tools.ietf.org/html/rfc6570)343- _url_ (deprecated): [URL record](https://url.spec.whatwg.org/#concept-url).344- _email_: email address.345- _hostname_: host name according to [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5).346- _ipv4_: IP address v4.347- _ipv6_: IP address v6.348- _regex_: tests whether a string is a valid regular expression by passing it to RegExp constructor.349- _uuid_: Universally Unique IDentifier according to [RFC4122](http://tools.ietf.org/html/rfc4122).350- _json-pointer_: JSON-pointer according to [RFC6901](https://tools.ietf.org/html/rfc6901).351- _relative-json-pointer_: relative JSON-pointer according to [this draft](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00).352 353__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.354 355There are two modes of format validation: `fast` and `full`. This mode affects formats `date`, `time`, `date-time`, `uri`, `uri-reference`, and `email`. See [Options](#options) for details.356 357You can add additional formats and replace any of the formats above using [addFormat](#api-addformat) method.358 359The 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 allow specific format(s) that will be ignored. See [Options](#options) for details.360 361You can find regular expressions used for format validation and the sources that were used in [formats.js](https://github.com/ajv-validator/ajv/blob/master/lib/compile/formats.js).362 363 364## <a name="ref"></a>Combining schemas with $ref365 366You can structure your validation logic across multiple schema files and have schemas reference each other using `$ref` keyword.367 368Example:369 370```javascript371var schema = {372 "$id": "http://example.com/schemas/schema.json",373 "type": "object",374 "properties": {375 "foo": { "$ref": "defs.json#/definitions/int" },376 "bar": { "$ref": "defs.json#/definitions/str" }377 }378};379 380var defsSchema = {381 "$id": "http://example.com/schemas/defs.json",382 "definitions": {383 "int": { "type": "integer" },384 "str": { "type": "string" }385 }386};387```388 389Now to compile your schema you can either pass all schemas to Ajv instance:390 391```javascript392var ajv = new Ajv({schemas: [schema, defsSchema]});393var validate = ajv.getSchema('http://example.com/schemas/schema.json');394```395 396or use `addSchema` method:397 398```javascript399var ajv = new Ajv;400var validate = ajv.addSchema(defsSchema)401 .compile(schema);402```403 404See [Options](#options) and [addSchema](#api) method.405 406__Please note__:407- `$ref` is resolved as the uri-reference using schema $id as the base URI (see the example).408- References can be recursive (and mutually recursive) to implement the schemas for different data structures (such as linked lists, trees, graphs, etc.).409- 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.410- The actual location of the schema file in the file system is not used.411- 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.412- You cannot have the same $id (or the schema identifier) used for more than one schema - the exception will be thrown.413- 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).414 415 416## $data reference417 418With `$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.419 420`$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.421 422The 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).423 424Examples.425 426This schema requires that the value in property `smaller` is less or equal than the value in the property larger:427 428```javascript429var ajv = new Ajv({$data: true});430 431var schema = {432 "properties": {433 "smaller": {434 "type": "number",435 "maximum": { "$data": "1/larger" }436 },437 "larger": { "type": "number" }438 }439};440 441var validData = {442 smaller: 5,443 larger: 7444};445 446ajv.validate(schema, validData); // true447```448 449This schema requires that the properties have the same format as their field names:450 451```javascript452var schema = {453 "additionalProperties": {454 "type": "string",455 "format": { "$data": "0#" }456 }457};458 459var validData = {460 'date-time': '1963-06-19T08:30:06.283185Z',461 email: 'joe.bloggs@example.com'462}463```464 465`$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.466 467 468## $merge and $patch keywords469 470With the package [ajv-merge-patch](https://github.com/ajv-validator/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).471 472To add keywords `$merge` and `$patch` to Ajv instance use this code:473 474```javascript475require('ajv-merge-patch')(ajv);476```477 478Examples.479 480Using `$merge`:481 482```json483{484 "$merge": {485 "source": {486 "type": "object",487 "properties": { "p": { "type": "string" } },488 "additionalProperties": false489 },490 "with": {491 "properties": { "q": { "type": "number" } }492 }493 }494}495```496 497Using `$patch`:498 499```json500{501 "$patch": {502 "source": {503 "type": "object",504 "properties": { "p": { "type": "string" } },505 "additionalProperties": false506 },507 "with": [508 { "op": "add", "path": "/properties/q", "value": { "type": "number" } }509 ]510 }511}512```513 514The schemas above are equivalent to this schema:515 516```json517{518 "type": "object",519 "properties": {520 "p": { "type": "string" },521 "q": { "type": "number" }522 },523 "additionalProperties": false524}525```526 527The 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.528 529See the package [ajv-merge-patch](https://github.com/ajv-validator/ajv-merge-patch) for more information.530 531 532## Defining custom keywords533 534The advantages of using custom keywords are:535 536- allow creating validation scenarios that cannot be expressed using JSON Schema537- simplify your schemas538- help bringing a bigger part of the validation logic to your schemas539- make your schemas more expressive, less verbose and closer to your application domain540- 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 validated541 542If 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).543 544The 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.545 546You 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.547 548Ajv allows defining keywords with:549- validation function550- compilation function551- macro function552- inline compilation function that should return code (as string) that will be inlined in the currently compiled schema.553 554Example. `range` and `exclusiveRange` keywords using compiled schema:555 556```javascript557ajv.addKeyword('range', {558 type: 'number',559 compile: function (sch, parentSchema) {560 var min = sch[0];561 var max = sch[1];562 563 return parentSchema.exclusiveRange === true564 ? function (data) { return data > min && data < max; }565 : function (data) { return data >= min && data <= max; }566 }567});568 569var schema = { "range": [2, 4], "exclusiveRange": true };570var validate = ajv.compile(schema);571console.log(validate(2.01)); // true572console.log(validate(3.99)); // true573console.log(validate(2)); // false574console.log(validate(4)); // false575```576 577Several custom keywords (typeof, instanceof, range and propertyNames) are defined in [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package - they can be used for your schemas and as a starting point for your own custom keywords.578 579See [Defining custom keywords](https://github.com/ajv-validator/ajv/blob/master/CUSTOM.md) for more details.580 581 582## Asynchronous schema compilation583 584During asynchronous compilation remote references are loaded using supplied function. See `compileAsync` [method](#api-compileAsync) and `loadSchema` [option](#options).585 586Example:587 588```javascript589var ajv = new Ajv({ loadSchema: loadSchema });590 591ajv.compileAsync(schema).then(function (validate) {592 var valid = validate(data);593 // ...594});595 596function loadSchema(uri) {597 return request.json(uri).then(function (res) {598 if (res.statusCode >= 400)599 throw new Error('Loading error: ' + res.statusCode);600 return res.body;601 });602}603```604 605__Please note__: [Option](#options) `missingRefs` should NOT be set to `"ignore"` or `"fail"` for asynchronous compilation to work.606 607 608## Asynchronous validation609 610Example in Node.js REPL: https://tonicdev.com/esp/ajv-asynchronous-validation611 612You 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)).613 614If 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.615 616__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.617 618Validation 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).619 620Ajv 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).621 622The 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.623 624Validation 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.625 626 627Example:628 629```javascript630var ajv = new Ajv;631// require('ajv-async')(ajv);632 633ajv.addKeyword('idExists', {634 async: true,635 type: 'number',636 validate: checkIdExists637});638 639 640function checkIdExists(schema, data) {641 return knex(schema.table)642 .select('id')643 .where('id', data)644 .then(function (rows) {645 return !!rows.length; // true if record is found646 });647}648 649var schema = {650 "$async": true,651 "properties": {652 "userId": {653 "type": "integer",654 "idExists": { "table": "users" }655 },656 "postId": {657 "type": "integer",658 "idExists": { "table": "posts" }659 }660 }661};662 663var validate = ajv.compile(schema);664 665validate({ userId: 1, postId: 19 })666.then(function (data) {667 console.log('Data is valid', data); // { userId: 1, postId: 19 }668})669.catch(function (err) {670 if (!(err instanceof Ajv.ValidationError)) throw err;671 // data is invalid672 console.log('Validation errors:', err.errors);673});674```675 676### Using transpilers with asynchronous validation functions.677 678[ajv-async](https://github.com/ajv-validator/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).679 680 681#### Using nodent682 683```javascript684var ajv = new Ajv;685require('ajv-async')(ajv);686// in the browser if you want to load ajv-async bundle separately you can:687// window.ajvAsync(ajv);688var validate = ajv.compile(schema); // transpiled es7 async function689validate(data).then(successFunc).catch(errorFunc);690```691 692 693#### Using other transpilers694 695```javascript696var ajv = new Ajv({ processCode: transpileFunc });697var validate = ajv.compile(schema); // transpiled es7 async function698validate(data).then(successFunc).catch(errorFunc);699```700 701See [Options](#options).702 703 704## Security considerations705 706JSON Schema, if properly used, can replace data sanitisation. It doesn't replace other API security considerations. It also introduces additional security aspects to consider.707 708 709##### Security contact710 711To report a security vulnerability, please use the712[Tidelift security contact](https://tidelift.com/security).713Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.714 715 716##### Untrusted schemas717 718Ajv 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.719 720If your schemas are received from untrusted sources (or generated from untrusted data) there are several scenarios you need to prevent:721- compiling schemas can cause stack overflow (if they are too deep)722- compiling schemas can be slow (e.g. [#557](https://github.com/ajv-validator/ajv/issues/557))723- validating certain data can be slow724 725It 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.726 727Regardless the measures you take, using untrusted schemas increases security risks.728 729 730##### Circular references in JavaScript objects731 732Ajv does not support schemas and validated data that have circular references in objects. See [issue #802](https://github.com/ajv-validator/ajv/issues/802).733 734An 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.735 736 737##### Security risks of trusted schemas738 739Some keywords in JSON Schemas can lead to very slow validation for certain data. These keywords include (but may be not limited to):740 741- `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)).742- `patternProperties` for large property names - use `propertyNames` to mitigate, but some regular expressions can have exponential evaluation time as well.743- `uniqueItems` for large non-scalar arrays - use `maxItems` to mitigate744 745__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).746 747You can validate your JSON schemas against [this meta-schema](https://github.com/ajv-validator/ajv/blob/master/lib/refs/json-schema-secure.json) to check that these recommendations are followed:748 749```javascript750const isSchemaSecure = ajv.compile(require('ajv/lib/refs/json-schema-secure.json'));751 752const schema1 = {format: 'email'};753isSchemaSecure(schema1); // false754 755const schema2 = {format: 'email', maxLength: MAX_LENGTH};756isSchemaSecure(schema2); // true757```758 759__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.760 761 762##### Content Security Policies (CSP)763See [Ajv and Content Security Policies (CSP)](#ajv-and-content-security-policies-csp)764 765 766## ReDoS attack767 768Certain regular expressions can lead to the exponential evaluation time even with relatively short strings.769 770Please 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.771 772__Please note__: some formats that Ajv implements use [regular expressions](https://github.com/ajv-validator/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:773 774- making assessment of "format" implementations in Ajv.775- using `format: 'fast'` option that simplifies some of the regular expressions (although it does not guarantee that they are safe).776- 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.777- disabling format validation by ignoring "format" keyword with option `format: false`778 779Whatever 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.780 781 782## Filtering data783 784With [option `removeAdditional`](#options) (added by [andyscott](https://github.com/andyscott)) you can filter data during the validation.785 786This option modifies original data.787 788Example:789 790```javascript791var ajv = new Ajv({ removeAdditional: true });792var schema = {793 "additionalProperties": false,794 "properties": {795 "foo": { "type": "number" },796 "bar": {797 "additionalProperties": { "type": "number" },798 "properties": {799 "baz": { "type": "string" }800 }801 }802 }803}804 805var data = {806 "foo": 0,807 "additional1": 1, // will be removed; `additionalProperties` == false808 "bar": {809 "baz": "abc",810 "additional2": 2 // will NOT be removed; `additionalProperties` != false811 },812}813 814var validate = ajv.compile(schema);815 816console.log(validate(data)); // true817console.log(data); // { "foo": 0, "bar": { "baz": "abc", "additional2": 2 }818```819 820If `removeAdditional` option in the example above were `"all"` then both `additional1` and `additional2` properties would have been removed.821 822If 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).823 824__Please note__: If you use `removeAdditional` option with `additionalProperties` keyword inside `anyOf`/`oneOf` keywords your validation can fail with this schema, for example:825 826```json827{828 "type": "object",829 "oneOf": [830 {831 "properties": {832 "foo": { "type": "string" }833 },834 "required": [ "foo" ],835 "additionalProperties": false836 },837 {838 "properties": {839 "bar": { "type": "integer" }840 },841 "required": [ "bar" ],842 "additionalProperties": false843 }844 ]845}846```847 848The 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.849 850With 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).851 852While this behaviour is unexpected (issues [#129](https://github.com/ajv-validator/ajv/issues/129), [#134](https://github.com/ajv-validator/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:853 854```json855{856 "type": "object",857 "properties": {858 "foo": { "type": "string" },859 "bar": { "type": "integer" }860 },861 "additionalProperties": false,862 "oneOf": [863 { "required": [ "foo" ] },864 { "required": [ "bar" ] }865 ]866}867```868 869The schema above is also more efficient - it will compile into a faster function.870 871 872## Assigning defaults873 874With [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.875 876With the option value `"empty"` properties and items equal to `null` or `""` (empty string) will be considered missing and assigned defaults.877 878This option modifies original data.879 880__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.881 882 883Example 1 (`default` in `properties`):884 885```javascript886var ajv = new Ajv({ useDefaults: true });887var schema = {888 "type": "object",889 "properties": {890 "foo": { "type": "number" },891 "bar": { "type": "string", "default": "baz" }892 },893 "required": [ "foo", "bar" ]894};895 896var data = { "foo": 1 };897 898var validate = ajv.compile(schema);899 900console.log(validate(data)); // true901console.log(data); // { "foo": 1, "bar": "baz" }902```903 904Example 2 (`default` in `items`):905 906```javascript907var schema = {908 "type": "array",909 "items": [910 { "type": "number" },911 { "type": "string", "default": "foo" }912 ]913}914 915var data = [ 1 ];916 917var validate = ajv.compile(schema);918 919console.log(validate(data)); // true920console.log(data); // [ 1, "foo" ]921```922 923`default` keywords in other cases are ignored:924 925- not in `properties` or `items` subschemas926- in schemas inside `anyOf`, `oneOf` and `not` (see [#42](https://github.com/ajv-validator/ajv/issues/42))927- in `if` subschema of `switch` keyword928- in schemas generated by custom macro keywords929 930The [`strictDefaults` option](#options) customizes Ajv's behavior for the defaults that Ajv ignores (`true` raises an error, and `"log"` outputs a warning).931 932 933## Coercing data types934 935When 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.936 937This option modifies original data.938 939__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.940 941 942Example 1:943 944```javascript945var ajv = new Ajv({ coerceTypes: true });946var schema = {947 "type": "object",948 "properties": {949 "foo": { "type": "number" },950 "bar": { "type": "boolean" }951 },952 "required": [ "foo", "bar" ]953};954 955var data = { "foo": "1", "bar": "false" };956 957var validate = ajv.compile(schema);958 959console.log(validate(data)); // true960console.log(data); // { "foo": 1, "bar": false }961```962 963Example 2 (array coercions):964 965```javascript966var ajv = new Ajv({ coerceTypes: 'array' });967var schema = {968 "properties": {969 "foo": { "type": "array", "items": { "type": "number" } },970 "bar": { "type": "boolean" }971 }972};973 974var data = { "foo": "1", "bar": ["false"] };975 976var validate = ajv.compile(schema);977 978console.log(validate(data)); // true979console.log(data); // { "foo": [1], "bar": false }980```981 982The 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).983 984See [Coercion rules](https://github.com/ajv-validator/ajv/blob/master/COERCION.md) for details.985 986 987## API988 989##### new Ajv(Object options) -> Object990 991Create Ajv instance.992 993 994##### .compile(Object schema) -> Function<Object data>995 996Generate validating function and cache the compiled schema for future use.997 998Validating 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.999 1000The 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).1001 1002 1003##### <a name="api-compileAsync"></a>.compileAsync(Object schema [, Boolean meta] [, Function callback]) -> Promise1004 1005Asynchronous 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:1006 1007- missing schema can't be loaded (`loadSchema` returns a Promise that rejects).1008- a schema containing a missing reference is loaded, but the reference cannot be resolved.1009- schema (or some loaded/referenced schema) is invalid.1010 1011The function compiles schema and loads the first missing schema (or meta-schema) until all missing schemas are loaded.1012 1013You can asynchronously compile meta-schema by passing `true` as the second parameter.1014 1015See example in [Asynchronous compilation](#asynchronous-schema-compilation).1016 1017 1018##### .validate(Object schema|String key|String ref, data) -> Boolean1019 1020Validate data using passed schema (it will be compiled and cached).1021 1022Instead 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.1023 1024Validation errors will be available in the `errors` property of Ajv instance (`null` if there were no errors).1025 1026__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.1027 1028If the schema is asynchronous (has `$async` keyword on the top level) this method returns a Promise. See [Asynchronous validation](#asynchronous-validation).1029 1030 1031##### .addSchema(Array<Object>|Object schema [, String key]) -> Ajv1032 1033Add 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.1034 1035Array of schemas can be passed (schemas should have ids), the second parameter will be ignored.1036 1037Key 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.1038 1039 1040Once the schema is added, it (and all the references inside it) can be referenced in other schemas and used to validate data.1041 1042Although `addSchema` does not compile schemas, explicit compilation is not required - the schema will be compiled when it is used first time.1043 1044By 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.1045 1046__Please note__: Ajv uses the [method chaining syntax](https://en.wikipedia.org/wiki/Method_chaining) for all methods with the prefix `add*` and `remove*`.1047This allows you to do nice things like the following.1048 1049```javascript1050var validate = new Ajv().addSchema(schema).addFormat(name, regex).getSchema(uri);1051```1052 1053##### .addMetaSchema(Array<Object>|Object schema [, String key]) -> Ajv1054 1055Adds 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).1056 1057There 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`.1058 1059 1060##### <a name="api-validateschema"></a>.validateSchema(Object schema) -> Boolean1061 1062Validates schema. This method should be used to validate schemas rather than `validate` due to the inconsistency of `uri` format in JSON Schema standard.1063 1064By default this method is called automatically when the schema is added, so you rarely need to use it directly.1065 1066If schema doesn't have `$schema` property, it is validated against draft 6 meta-schema (option `meta` should not be false).1067 1068If schema has `$schema` property, then the schema with this id (that should be previously added) is used to validate passed schema.1069 1070Errors will be available at `ajv.errors`.1071 1072 1073##### .getSchema(String key) -> Function<Object data>1074 1075Retrieve 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.1076 1077 1078##### .removeSchema([Object schema|String key|String ref|RegExp pattern]) -> Ajv1079 1080Remove added/cached schema. Even if schema is referenced by other schemas it can be safely removed as dependent schemas have local references.1081 1082Schema can be removed using:1083- key passed to `addSchema`1084- it's full reference (id)1085- RegExp that should match schema id or key (meta-schemas won't be removed)1086- actual schema object that will be stable-stringified to remove schema from cache1087 1088If no parameter is passed all schemas but meta-schemas will be removed and the cache will be cleared.1089 1090 1091##### <a name="api-addformat"></a>.addFormat(String name, String|RegExp|Function|Object format) -> Ajv1092 1093Add custom format to validate strings or numbers. It can also be used to replace pre-defined formats for Ajv instance.1094 1095Strings are converted to RegExp.1096 1097Function should return validation result as `true` or `false`.1098 1099If object is passed it should have properties `validate`, `compare` and `async`:1100 1101- _validate_: a string, RegExp or a function as described above.1102- _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/ajv-validator/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.1103- _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`.1104- _type_: an optional type of data that the format applies to. It can be `"string"` (default) or `"number"` (see https://github.com/ajv-validator/ajv/issues/291#issuecomment-259923858). If the type of data is different, the validation will pass.1105 1106Custom formats can be also added via `formats` option.1107 1108 1109##### <a name="api-addkeyword"></a>.addKeyword(String keyword, Object definition) -> Ajv1110 1111Add custom validation keyword to Ajv instance.1112 1113Keyword 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.1114 1115Keyword must start with a letter, `_` or `$`, and may continue with letters, numbers, `_`, `$`, or `-`.1116It is recommended to use an application-specific prefix for keywords to avoid current and future name collisions.1117 1118Example Keywords:1119- `"xyz-example"`: valid, and uses prefix for the xyz project to avoid name collisions.1120- `"example"`: valid, but not recommended as it could collide with future versions of JSON Schema etc.1121- `"3-example"`: invalid as numbers are not allowed to be the first character in a keyword1122 1123Keyword definition is an object with the following properties:1124 1125- _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.1126- _validate_: validating function1127- _compile_: compiling function1128- _macro_: macro function1129- _inline_: compiling function that returns code (as string)1130- _schema_: an optional `false` value used with "validate" keyword to not pass schema1131- _metaSchema_: an optional meta-schema for keyword schema1132- _dependencies_: an optional list of properties that must be present in the parent schema - it will be checked during schema compilation1133- _modifying_: `true` MUST be passed if keyword modifies data1134- _statements_: `true` can be passed in case inline keyword generates statements (as opposed to expression)1135- _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.1136- _$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).1137- _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.1138- _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.1139 1140_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.1141 1142__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.1143 1144See [Defining custom keywords](#defining-custom-keywords) for more details.1145 1146 1147##### .getKeyword(String keyword) -> Object|Boolean1148 1149Returns custom keyword definition, `true` for pre-defined keywords and `false` if the keyword is unknown.1150 1151 1152##### .removeKeyword(String keyword) -> Ajv1153 1154Removes custom or pre-defined keyword so you can redefine them.1155 1156While 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.1157 1158__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.1159 1160 1161##### .errorsText([Array<Object> errors [, Object options]]) -> String1162 1163Returns the text with all errors in a String.1164 1165Options can have properties `separator` (string used to separate errors, ", " by default) and `dataVar` (the variable name that dataPaths are prefixed with, "data" by default).1166 1167 1168## Options1169 1170Defaults:1171 1172```javascript1173{1174 // validation and reporting options:1175 $data: false,1176 allErrors: false,1177 verbose: false,1178 $comment: false, // NEW in Ajv version 6.01179 jsonPointers: false,1180 uniqueItems: true,1181 unicode: true,1182 nullable: false,1183 format: 'fast',1184 formats: {},1185 unknownFormats: true,1186 schemas: {},1187 logger: undefined,1188 // referenced schema options:1189 schemaId: '$id',1190 missingRefs: true,1191 extendRefs: 'ignore', // recommended 'fail'1192 loadSchema: undefined, // function(uri: string): Promise {}1193 // options to modify validated data:1194 removeAdditional: false,1195 useDefaults: false,1196 coerceTypes: false,1197 // strict mode options1198 strictDefaults: false,1199 strictKeywords: false,1200 strictNumbers: false,