diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index c77c8e485..88fc551fa 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,2 +1,3 @@
+github: epoberezkin
tidelift: "npm/ajv"
open_collective: "ajv"
diff --git a/.github/ISSUE_TEMPLATE/typescript.md b/.github/ISSUE_TEMPLATE/typescript.md
new file mode 100644
index 000000000..7385349b0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/typescript.md
@@ -0,0 +1,42 @@
+---
+name: Missing or incorrect type definition
+about: Please use for issues related to typescript types
+title: ''
+labels: 'typescript'
+assignees: ''
+
+---
+
+
+
+**What version of Ajv are you using? Does the issue happen if you use the latest version?**
+
+
+**Your typescript code**
+
+
+
+```typescript
+
+
+```
+
+
+**Typescript compiler error messages**
+
+```
+
+
+```
+
+**Describe the change that should be made to address the issue?**
+
+
+**Are you going to resolve the issue?**
diff --git a/FAQ.md b/FAQ.md
index 472a5edb0..36ac967cd 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -83,7 +83,7 @@ There are several ways to implement the described logic that would allow two pro
##### Why the validation fails when I use option `removeAdditional` with the keyword `anyOf`/etc.?
-This problem is related to the problem explained above - properties treated as additional in the sence of `additionalProperties` keyword, based on `properties`/`patternProperties` keyword in the same schema object.
+This problem is related to the problem explained above - properties treated as additional in the sense of `additionalProperties` keyword, based on `properties`/`patternProperties` keyword in the same schema object.
See the exemple in [Filtering Data](https://github.com/epoberezkin/ajv#filtering-data) section of readme.
diff --git a/README.md b/README.md
index be013ebb0..75e5c850b 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,49 @@ The fastest JSON Schema validator for Node.js and browser. Supports draft-04/06/
[](https://opencollective.com/ajv) [](https://www.npmjs.com/package/ajv)
[](https://www.npmjs.com/package/ajv)
[](https://coveralls.io/github/epoberezkin/ajv?branch=master)
-[](https://greenkeeper.io/)
[](https://gitter.im/ajv-validator/ajv)
+[](https://github.com/sponsors/epoberezkin)
+
+## Please [sponsor Ajv](https://github.com/sponsors/epoberezkin)
+
+Dear Ajv users! ❤️
+
+I ask you to support the development of Ajv with donations. 🙏
+
+Since 2015 Ajv has become widely used, thanks to your help and contributions:
+
+- **90** contributors 🏗
+- **5,000** dependent npm packages ⚙️
+- **7,000** github stars, from GitHub users [all over the world](https://www.google.com/maps/d/u/0/viewer?mid=1MGRV8ciFUGIbO1l0EKFWNJGYE7iSkDxP&ll=-3.81666561775622e-14%2C4.821737100000007&z=2) ⭐️
+- **5,000,000** dependent repositories on GitHub 🚀
+- **120,000,000** npm downloads per month! 💯
+
+Your donations will fund futher development - small and large improvements, support of the next versions of JSON Schema specification, and, possibly, the code should be migrated to TypeScript to make it more maintainable.
+
+I will greatly appreciate anything you can help with to make it happen:
+
+- a **personal** donation - from $2 ☕️
+- your **company** donation - from $10 🍔
+- a **sponsorship** to get promoted on Ajv or related packages - from $50 💰
+- an **introduction** to a sponsor who would benefit from the promotion on Ajv page 🤝
+
+| Please [make donations via my GitHub sponsors page](https://github.com/sponsors/epoberezkin) ‼️ **GitHub will DOUBLE them** ‼️ |
+|---|
+
+#### Open Collective sponsors
+
+
+
+
+
+
+
+
+
+
+
+
+
## Using version 6
@@ -131,7 +172,11 @@ Try it in the Node.js REPL: https://tonicdev.com/npm/ajv
The fastest validation call:
```javascript
+// Node.js require:
var Ajv = require('ajv');
+// or ESM/TypeScript import
+import Ajv from 'ajv';
+
var ajv = new Ajv(); // options can be passed, e.g. {allErrors: true}
var validate = ajv.compile(schema);
var valid = validate(data);
@@ -165,6 +210,10 @@ The best performance is achieved when using compiled functions returned by `comp
__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)
+__Note for TypeScript users__: `ajv` provides its own TypeScript declarations
+out of the box, so you don't need to install the deprecated `@types/ajv`
+module.
+
## Using in browser
@@ -328,7 +377,7 @@ __Please note__:
## $data reference
-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/json-schema/wiki/$data-(v5-proposal)) for more information about how it works.
+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.
`$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.
@@ -1144,12 +1193,13 @@ Defaults:
- `"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.
- `false` - ignore all format keywords.
- _formats_: an object with custom formats. Keys and values will be passed to `addFormat` method.
+- _keywords_: an object with custom keywords. Keys and values will be passed to `addKeyword` method.
- _unknownFormats_: handling of unknown formats. Option values:
- `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.
- `[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.
- `"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.
- _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.
-- _logger_: sets the logging method. Default is the global `console` object that should have methods `log`, `warn` and `error`. Option values:
+- _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:
- custom logger - it should have methods `log`, `warn` and `error`. If any of these methods is missing an exception will be thrown.
- `false` - logging is disabled.
@@ -1287,6 +1337,28 @@ Properties of `params` object in errors depend on the keyword that failed valida
- custom keywords (in case keyword definition doesn't create errors) - property `keyword` (the keyword name).
+### Error logging
+
+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.
+- **Required Methods**: `log`, `warn`, `error`
+
+```javascript
+var otherLogger = new OtherLogger();
+var ajv = new Ajv({
+ logger: {
+ log: console.log.bind(console),
+ warn: function warn() {
+ otherLogger.logWarn.apply(otherLogger, arguments);
+ },
+ error: function error() {
+ otherLogger.logError.apply(otherLogger, arguments);
+ console.error.apply(console, arguments);
+ }
+ }
+});
+```
+
+
## Plugins
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:
@@ -1309,7 +1381,7 @@ If you have published a useful plugin please submit a PR to add it to the next s
- [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) - plugin with custom validation keywords (select, typeof, etc.)
- [ajv-merge-patch](https://github.com/epoberezkin/ajv-merge-patch) - plugin with keywords $merge and $patch
- [ajv-pack](https://github.com/epoberezkin/ajv-pack) - produces a compact module exporting validation functions
-
+- [ajv-formats-draft2019](https://github.com/luzlab/ajv-formats-draft2019) - format validators for draft2019 that aren't already included in ajv (ie. `idn-hostname`, `idn-email`, `iri`, `iri-reference` and `duration`).
## Some packages using Ajv
diff --git a/lib/ajv.d.ts b/lib/ajv.d.ts
index 5e7cfa7da..cb600e168 100644
--- a/lib/ajv.d.ts
+++ b/lib/ajv.d.ts
@@ -80,9 +80,9 @@ declare namespace ajv {
/**
* Get compiled schema from the instance by `key` or `ref`.
* @param {string} keyRef `key` that was passed to `addSchema` or full schema reference (`schema.id` or resolved id).
- * @return {Function} schema validating function (with property `schema`).
+ * @return {Function} schema validating function (with property `schema`). Returns undefined if keyRef can't be resolved to an existing schema.
*/
- getSchema(keyRef: string): ValidateFunction;
+ getSchema(keyRef: string): ValidateFunction | undefined;
/**
* Remove cached schema(s).
* If no parameter is passed all schemas but meta-schemas are removed.
@@ -169,8 +169,9 @@ declare namespace ajv {
jsonPointers?: boolean;
uniqueItems?: boolean;
unicode?: boolean;
- format?: string;
+ format?: false | string;
formats?: object;
+ keywords?: object;
unknownFormats?: true | string[] | 'ignore';
schemas?: Array
+
+
+
+
+
+
+
+
+
## Using version 6
@@ -131,7 +172,11 @@ Try it in the Node.js REPL: https://tonicdev.com/npm/ajv
The fastest validation call:
```javascript
+// Node.js require:
var Ajv = require('ajv');
+// or ESM/TypeScript import
+import Ajv from 'ajv';
+
var ajv = new Ajv(); // options can be passed, e.g. {allErrors: true}
var validate = ajv.compile(schema);
var valid = validate(data);
@@ -165,6 +210,10 @@ The best performance is achieved when using compiled functions returned by `comp
__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)
+__Note for TypeScript users__: `ajv` provides its own TypeScript declarations
+out of the box, so you don't need to install the deprecated `@types/ajv`
+module.
+
## Using in browser
@@ -328,7 +377,7 @@ __Please note__:
## $data reference
-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/json-schema/wiki/$data-(v5-proposal)) for more information about how it works.
+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.
`$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.
@@ -1144,12 +1193,13 @@ Defaults:
- `"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.
- `false` - ignore all format keywords.
- _formats_: an object with custom formats. Keys and values will be passed to `addFormat` method.
+- _keywords_: an object with custom keywords. Keys and values will be passed to `addKeyword` method.
- _unknownFormats_: handling of unknown formats. Option values:
- `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.
- `[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.
- `"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.
- _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.
-- _logger_: sets the logging method. Default is the global `console` object that should have methods `log`, `warn` and `error`. Option values:
+- _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:
- custom logger - it should have methods `log`, `warn` and `error`. If any of these methods is missing an exception will be thrown.
- `false` - logging is disabled.
@@ -1287,6 +1337,28 @@ Properties of `params` object in errors depend on the keyword that failed valida
- custom keywords (in case keyword definition doesn't create errors) - property `keyword` (the keyword name).
+### Error logging
+
+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.
+- **Required Methods**: `log`, `warn`, `error`
+
+```javascript
+var otherLogger = new OtherLogger();
+var ajv = new Ajv({
+ logger: {
+ log: console.log.bind(console),
+ warn: function warn() {
+ otherLogger.logWarn.apply(otherLogger, arguments);
+ },
+ error: function error() {
+ otherLogger.logError.apply(otherLogger, arguments);
+ console.error.apply(console, arguments);
+ }
+ }
+});
+```
+
+
## Plugins
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:
@@ -1309,7 +1381,7 @@ If you have published a useful plugin please submit a PR to add it to the next s
- [ajv-keywords](https://github.com/epoberezkin/ajv-keywords) - plugin with custom validation keywords (select, typeof, etc.)
- [ajv-merge-patch](https://github.com/epoberezkin/ajv-merge-patch) - plugin with keywords $merge and $patch
- [ajv-pack](https://github.com/epoberezkin/ajv-pack) - produces a compact module exporting validation functions
-
+- [ajv-formats-draft2019](https://github.com/luzlab/ajv-formats-draft2019) - format validators for draft2019 that aren't already included in ajv (ie. `idn-hostname`, `idn-email`, `iri`, `iri-reference` and `duration`).
## Some packages using Ajv
diff --git a/lib/ajv.d.ts b/lib/ajv.d.ts
index 5e7cfa7da..cb600e168 100644
--- a/lib/ajv.d.ts
+++ b/lib/ajv.d.ts
@@ -80,9 +80,9 @@ declare namespace ajv {
/**
* Get compiled schema from the instance by `key` or `ref`.
* @param {string} keyRef `key` that was passed to `addSchema` or full schema reference (`schema.id` or resolved id).
- * @return {Function} schema validating function (with property `schema`).
+ * @return {Function} schema validating function (with property `schema`). Returns undefined if keyRef can't be resolved to an existing schema.
*/
- getSchema(keyRef: string): ValidateFunction;
+ getSchema(keyRef: string): ValidateFunction | undefined;
/**
* Remove cached schema(s).
* If no parameter is passed all schemas but meta-schemas are removed.
@@ -169,8 +169,9 @@ declare namespace ajv {
jsonPointers?: boolean;
uniqueItems?: boolean;
unicode?: boolean;
- format?: string;
+ format?: false | string;
formats?: object;
+ keywords?: object;
unknownFormats?: true | string[] | 'ignore';
schemas?: Array