The ajv npm package is a fast JSON Schema validator that allows you to validate JSON data against a JSON schema. It supports the latest JSON Schema draft-07 and has several extensions. It can be used for data validation, data sanitization, and to ensure that JSON documents comply with a predefined schema.
Validate data against a JSON Schema
This feature allows you to compile a JSON Schema and use it to validate JSON data. If the data does not conform to the schema, the errors can be logged or handled as needed.
{"const Ajv = require('ajv');
const ajv = new Ajv();
const schema = {
"type": "object",
"properties": {
"foo": {"type": "integer"},
"bar": {"type": "string"}
},
"required": ["foo"]
};
const validate = ajv.compile(schema);
const valid = validate({foo: 1, bar: 'abc'});
if (!valid) console.log(validate.errors);"}Add custom keywords
Ajv allows you to define custom keywords for a JSON Schema, which can be used to create custom validation rules that are not defined in the JSON Schema specification.
{"const Ajv = require('ajv');
const ajv = new Ajv();
ajv.addKeyword('even', {
validate: function(schema, data) {
return data % 2 === 0;
}
});
const schema = {"even": true};
const validate = ajv.compile(schema);
const valid = validate(2); // true
const invalid = validate(3); // false"}Asynchronous validation
Ajv supports asynchronous schema compilation, which is useful when your JSON Schema depends on other schemas that need to be fetched remotely.
{"const Ajv = require('ajv');
const ajv = new Ajv({loadSchema: loadExternalSchema});
// Assume loadExternalSchema is a function that loads a schema asynchronously
ajv.compileAsync(schema).then(function(validate) {
const valid = validate(data);
if (!valid) console.log(validate.errors);
}).catch(function(err) {
console.error('Failed to compile schema:', err);
});"}Joi is a powerful schema description language and data validator for JavaScript. Unlike ajv, which focuses on JSON Schema, Joi allows you to create validation schemas using a fluent API. It is often used for validating data in REST APIs.
Tiny Validator (tv4) is a small and fast JSON Schema (v4) validator. It is less feature-rich compared to ajv and does not support the latest JSON Schema specifications, but it is suitable for simple validation tasks.
The jsonschema package is another validator for JSON Schema that supports draft-04/06/07. It is not as fast as ajv but provides a straightforward API for validating JSON data against schemas.
The fastest JSON Schema validator for Node.js and browser. Supports draft-06/07 (draft-04 is supported in v6).
Ajv has been awarded a grant from Mozilla’s Open Source Support (MOSS) program in the “Foundational Technology” track! It will sponsor the development of Ajv support of JSON Schema version 2019-09 and of JSON Type Definition.
Ajv also joined OpenJS Foundation – having this support will help ensure the longevity and stability of Ajv for all its users.
This blog post has more details.
I am looking for the long term maintainers of Ajv – working with ReadySet, 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.
Since I asked to support Ajv development 40 people and 6 organizations contributed via GitHub and OpenCollective - this support helped receiving the MOSS grant!
Your continuing support is very important - the funds will be used to develop and maintain Ajv once the next major version is released.
Please sponsor Ajv via:
Thank you.
JSON Schema draft-07 is published.
Ajv version 6.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).
Please note: To use Ajv with draft-06 schemas you need to explicitly add the meta-schema to the validator instance:
ajv.addMetaSchema(require("ajv/lib/refs/json-schema-draft-06.json"))
Please note: use Ajv v6 if you need draft-04 support - v7 does NOT support it.
Ajv generates code to turn JSON Schemas into super-fast validation functions that are efficient for v8 optimization.
Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:
Performance of different validators by json-schema-benchmark:
addSchema or compiled to be available)type keywordsconst, contains, propertyNames and if/then/elsetrue/false as a schema to always pass/fail).switch, patternRequired, formatMaximum / formatMinimum and formatExclusiveMaximum / formatExclusiveMinimum from JSON Schema extension proposals with ajv-keywords packagenpm install ajv
Try it in the Node.js REPL: https://runkit.com/npm/ajv
The fastest validation call:
// 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)
if (!valid) console.log(validate.errors)
or with less code
// ...
var valid = ajv.validate(schema, data)
if (!valid) console.log(ajv.errors)
// ...
or
// ...
var valid = ajv.addSchema(schema, "mySchema").validate("mySchema", data)
if (!valid) console.log(ajv.errorsText())
// ...
See API and Options for more details.
Ajv compiles schemas to functions and caches them in all cases (using schema serialized with fast-json-stable-stringify or another function passed via options), so that the next time the same schema is used (not necessarily the same object instance) it won't be compiled again.
The best performance is achieved when using compiled functions returned by compile or getSchema methods (there is no additional function call).
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
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.
You can require Ajv directly from the code you browserify - in this case Ajv will be a part of your bundle.
If you need to use Ajv in several bundles you can create a separate UMD bundle using npm run bundle script (thanks to siddo420).
Then you need to load Ajv in the browser:
<script src="ajv.min.js"></script>
This bundle can be used with different module systems; it creates global Ajv if no module system is found.
The browser bundle is available on cdnjs.
Ajv is tested with these browsers:
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).
If 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'.
:warning: NOTE, however, that unsafe-eval is NOT recommended in a secure CSP[1], as it has the potential to open the document to cross-site scripting (XSS) attacks.
In order to make use of Ajv without easing your CSP, you can pre-compile a schema using the CLI. This will transpile the schema JSON into a JavaScript file that exports a validate function that works simlarly to a schema compiled at runtime.
Note that pre-compilation of schemas is performed using ajv-pack and there are some limitations to the schema features it can compile. A successfully pre-compiled schema is equivalent to the same schema compiled at runtime.
CLI is available as a separate npm package ajv-cli. It supports:
Strict mode intends to prevent any unexpected behaviours or silently ignored mistakes in user schemas. It does not change any validation results compared with JSON Schema specification, but it makes some schemas invalid and throws exception or logs warning (with strict: "log" option) in case any restriction is violated.
The strict mode restrictions are below. To disable these restrictions use option strict: false.
JSON Schema section 6.5 requires to ignore unknown keywords. The motivation is to increase cross-platform portability of schemas, so that implementations that do not support certain keywords can still do partial validation.
The problems with this approach are:
By default Ajv fails schema compilation when unknown keywords are used. Users can explicitly define the keywords that should be allowed and ignored:
ajv.addKeyword("allowedKeyword")
or
ajv.addVocabulary(["allowed1", "allowed2"])
JSON Schema section 9.3.1.2 requires to ignore "additionalItems" keyword if "items" keyword is absent. This is inconsistent with the interaction of "additionalProperties" and "properties", and may cause unexpected results.
By default Ajv fails schema compilation when "additionalItems" is used without "items.
JSON Schema section 9.2.2 requires to ignore "if" (only annotations are collected) if both "then" and "else" are absent, and ignore "then"/"else" if "if" is absent.
By default Ajv fails schema compilation in these cases.
The expectation of users (see #196, #286) is that "patternProperties" only apply to properties not already defined in "properties" keyword, but JSON Schema section 9.3.2 defines these two keywords as independent. It means that to some properties two subschemas can be applied - one defined in "properties" keyword and another defined in "patternProperties" for the pattern matching this property.
By default Ajv fails schema compilation if a pattern in "patternProperties" matches a property in "properties" in the same schema.
In addition to allowing such patterns by using option strict: false, there is an option allowMatchingProperties: true to only allow this case without disabling other strict mode restrictions - there are some rare cases when this is necessary.
To reiterate, neither this nor other strict mode restrictions change the validation results - they only restrict which schemas are valid.
TODO
This will supercede unknownFormats option.
With useDefaults option Ajv modifies validated data by assigning defaults from the schema, but there are different limitations when the defaults can be ignored (see Assigning defaults). In strict mode Ajv fails schema compilation if such defaults are used in the schema.
Strict mode also affects number validation. By default Ajv fails {"type": "number"} (or "integer") validation for Infinity and NaN.
Ajv supports all validation keywords from draft-07 of JSON Schema standard:
With ajv-keywords package Ajv also supports validation keywords from JSON Schema extension proposals for JSON Schema standard:
required but with patterns that some property should match.See JSON Schema validation keywords for more details.
JSON Schema specification defines several annotation keywords that describe schema itself but do not perform any validation.
title and description: information about the data represented by that schema$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.default: a default value of the data instance, see Assigning defaults.examples (NEW in draft-06): an array of data instances. Ajv does not check the validity of these instances against the schema.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.).contentEncoding: RFC 2045, e.g., "base64".contentMediaType: RFC 2046, e.g., "image/png".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.
From version 7 Ajv does not include formats defined by JSON Schema specification - these and several others formats are provided by ajv-formats plugin.
To add all formats from this plugin:
const ajv = new Ajv()
require("ajv-formats")(ajv)
See ajv-formats documentation for further details.
It is recommended NOT to use "format" keyword implementations with untrusted data, as they use potentially unsafe regular expressions - see ReDoS attack.
Please note: if you need to use "format" keyword to validate untrusted data, you MUST assess their suitability and safety for your validation scenarios.
The following formats are defined in ajv-formats for string validation with "format" keyword:
date, time and date-time validate ranges in full mode and only regexp in fast mode (see options).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. These formats are available in ajv-formats-draft2019 plugin.
You can add (and replace) any formats using addFormat method.
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 allow specific format(s) that will be ignored. See Options for details.
You can find regular expressions used for format validation and the sources that were used in formats.js.
You can structure your validation logic across multiple schema files and have schemas reference each other using $ref keyword.
Example:
var schema = {
$id: "http://example.com/schemas/schema.json",
type: "object",
properties: {
foo: {$ref: "defs.json#/definitions/int"},
bar: {$ref: "defs.json#/definitions/str"},
},
}
var defsSchema = {
$id: "http://example.com/schemas/defs.json",
definitions: {
int: {type: "integer"},
str: {type: "string"},
},
}
Now to compile your schema you can either pass all schemas to Ajv instance:
var ajv = new Ajv({schemas: [schema, defsSchema]})
var validate = ajv.getSchema("http://example.com/schemas/schema.json")
or use addSchema method:
var ajv = new Ajv()
var validate = ajv.addSchema(defsSchema).compile(schema)
See Options and addSchema method.
Please note:
$ref is resolved as the uri-reference using schema $id as the base URI (see the example).addSchema method or as a property name in schemas option. This identifier can be used instead of (or in addition to) schema $id.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.With $data option you can use values from the validated data as the values for the schema keywords. See proposal 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.
The value of "$data" should be a JSON-pointer 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 (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).
Examples.
This schema requires that the value in property smaller is less or equal than the value in the property larger:
var ajv = new Ajv({$data: true})
var schema = {
properties: {
smaller: {
type: "number",
maximum: {$data: "1/larger"},
},
larger: {type: "number"},
},
}
var validData = {
smaller: 5,
larger: 7,
}
ajv.validate(schema, validData) // true
This schema requires that the properties have the same format as their field names:
var schema = {
additionalProperties: {
type: "string",
format: {$data: "0#"},
},
}
var validData = {
"date-time": "1963-06-19T08:30:06.283185Z",
email: "joe.bloggs@example.com",
}
$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.
With the package 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) and JSON Patch (RFC 6902).
To add keywords $merge and $patch to Ajv instance use this code:
require("ajv-merge-patch")(ajv)
Examples.
Using $merge:
{
"$merge": {
"source": {
"type": "object",
"properties": {"p": {"type": "string"}},
"additionalProperties": false
},
"with": {
"properties": {"q": {"type": "number"}}
}
}
}
Using $patch:
{
"$patch": {
"source": {
"type": "object",
"properties": {"p": {"type": "string"}},
"additionalProperties": false
},
"with": [{"op": "add", "path": "/properties/q", "value": {"type": "number"}}]
}
}
The schemas above are equivalent to this schema:
{
"type": "object",
"properties": {
"p": {"type": "string"},
"q": {"type": "number"}
},
"additionalProperties": false
}
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.
See the package ajv-merge-patch for more information.
The advantages of defining keywords are:
modifying option MUST be used in keyword definition) and/or create side effects while the data is being validatedIf 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).
The concerns you have to be aware of when extending JSON Schema standard with additional keywords are the portability and understanding of your schemas. You will have to support these keywords on other platforms and to properly document them so that everybody can understand and use your schemas.
You can define keywords with addKeyword method. Keywords are defined on the ajv instance level - new instances will not have previously defined keywords.
Ajv allows defining keywords with:
Example. range and exclusiveRange keywords using compiled schema:
ajv.addKeyword({
keyword: "range",
type: "number",
schemaType: "array",
implements: "exclusiveRange",
compile: ([min, max], parentSchema) =>
parentSchema.exclusiveRange === true
? (data) => data > min && data < max
: (data) => data >= min && data <= max,
})
const schema = {range: [2, 4], exclusiveRange: true}
const validate = ajv.compile(schema)
console.log(validate(2.01)) // true
console.log(validate(3.99)) // true
console.log(validate(2)) // false
console.log(validate(4)) // false
Several keywords (typeof, instanceof, range and propertyNames) are defined in ajv-keywords package - they can be used for your schemas and as a starting point for your own keywords.
See User-defined keywords for more details.
During asynchronous compilation remote references are loaded using supplied function. See compileAsync method and loadSchema option.
Example:
var ajv = new Ajv({loadSchema: loadSchema})
ajv.compileAsync(schema).then(function (validate) {
var valid = validate(data)
// ...
})
function loadSchema(uri) {
return request.json(uri).then(function (res) {
if (res.statusCode >= 400) throw new Error("Loading error: " + res.statusCode)
return res.body
})
}
Please note: Option missingRefs should NOT be set to "ignore" or "fail" for asynchronous compilation to work.
Example in Node.js REPL: https://runkit.com/esp/ajv-asynchronous-validation
You can define 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, addKeyword and User-defined keywords).
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.
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.
Validation function for an asynchronous format/keyword should return a promise that resolves with true or false (or rejects with new Ajv.ValidationError(errors) if you want to return errors from the keyword function).
Ajv compiles asynchronous schemas to async functions. Async functions are supported in Node.js 7+ and all modern browsers. You can supply a transpiler as a function via processCode option. See Options.
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.
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.
Example:
const ajv = new Ajv()
ajv.addKeyword({
keyword: "idExists"
async: true,
type: "number",
validate: checkIdExists,
})
function checkIdExists(schema, data) {
return knex(schema.table)
.select("id")
.where("id", data)
.then(function (rows) {
return !!rows.length // true if record is found
})
}
var schema = {
$async: true,
properties: {
userId: {
type: "integer",
idExists: {table: "users"},
},
postId: {
type: "integer",
idExists: {table: "posts"},
},
},
}
var validate = ajv.compile(schema)
validate({userId: 1, postId: 19})
.then(function (data) {
console.log("Data is valid", data) // { userId: 1, postId: 19 }
})
.catch(function (err) {
if (!(err instanceof Ajv.ValidationError)) throw err
// data is invalid
console.log("Validation errors:", err.errors)
})
var ajv = new Ajv({processCode: transpileFunc})
var validate = ajv.compile(schema) // transpiled es7 async function
validate(data).then(successFunc).catch(errorFunc)
See Options.
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.
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.
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.
If your schemas are received from untrusted sources (or generated from untrusted data) there are several scenarios you need to prevent:
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.
Regardless the measures you take, using untrusted schemas increases security risks.
Ajv does not support schemas and validated data that have circular references in objects. See issue #802.
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.
Some keywords in JSON Schemas can lead to very slow validation for certain data. These keywords include (but may be not limited to):
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).patternProperties for large property names - use propertyNames to mitigate, but some regular expressions can have exponential evaluation time as well.uniqueItems for large non-scalar arrays - use maxItems to mitigatePlease 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).
You can validate your JSON schemas against this meta-schema to check that these recommendations are followed:
const isSchemaSecure = ajv.compile(require("ajv/lib/refs/json-schema-secure.json"))
const schema1 = {format: "email"}
isSchemaSecure(schema1) // false
const schema2 = {format: "email", maxLength: MAX_LENGTH}
isSchemaSecure(schema2) // true
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.
See Ajv and Content Security Policies (CSP)
Certain regular expressions can lead to the exponential evaluation time even with relatively short strings.
Please assess the regular expressions you use in the schemas on their vulnerability to this attack - see safe-regex, for example.
Please note: some formats that Ajv implements use regular expressions 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:
format: 'fast' option that simplifies some of the regular expressions (although it does not guarantee that they are safe).format: falseWhatever 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.
With option removeAdditional (added by andyscott) you can filter data during the validation.
This option modifies original data.
Example:
var ajv = new Ajv({removeAdditional: true})
var schema = {
additionalProperties: false,
properties: {
foo: {type: "number"},
bar: {
additionalProperties: {type: "number"},
properties: {
baz: {type: "string"},
},
},
},
}
var data = {
foo: 0,
additional1: 1, // will be removed; `additionalProperties` == false
bar: {
baz: "abc",
additional2: 2, // will NOT be removed; `additionalProperties` != false
},
}
var validate = ajv.compile(schema)
console.log(validate(data)) // true
console.log(data) // { "foo": 0, "bar": { "baz": "abc", "additional2": 2 }
If removeAdditional option in the example above were "all" then both additional1 and additional2 properties would have been removed.
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).
Please note: If you use removeAdditional option with additionalProperties keyword inside anyOf/oneOf keywords your validation can fail with this schema, for example:
{
"type": "object",
"oneOf": [
{
"properties": {
"foo": {"type": "string"}
},
"required": ["foo"],
"additionalProperties": false
},
{
"properties": {
"bar": {"type": "integer"}
},
"required": ["bar"],
"additionalProperties": false
}
]
}
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.
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).
While this behaviour is unexpected (issues #129, #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:
{
"type": "object",
"properties": {
"foo": {"type": "string"},
"bar": {"type": "integer"}
},
"additionalProperties": false,
"oneOf": [{"required": ["foo"]}, {"required": ["bar"]}]
}
The schema above is also more efficient - it will compile into a faster function.
With option useDefaults 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.
With the option value "empty" properties and items equal to null or "" (empty string) will be considered missing and assigned defaults.
This option modifies original data.
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.
Example 1 (default in properties):
var ajv = new Ajv({useDefaults: true})
var schema = {
type: "object",
properties: {
foo: {type: "number"},
bar: {type: "string", default: "baz"},
},
required: ["foo", "bar"],
}
var data = {foo: 1}
var validate = ajv.compile(schema)
console.log(validate(data)) // true
console.log(data) // { "foo": 1, "bar": "baz" }
Example 2 (default in items):
var schema = {
type: "array",
items: [{type: "number"}, {type: "string", default: "foo"}],
}
var data = [1]
var validate = ajv.compile(schema)
console.log(validate(data)) // true
console.log(data) // [ 1, "foo" ]
With useDefaults option default keywords throws exception during schema compilation when used in:
properties or items subschemasanyOf, oneOf and not (see #42)if schemaThe strict mode option can change the behavior for these unsupported defaults (strict: false to ignore them, "log" to log a warning).
See Strict mode.
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.
This option modifies original data.
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.
Example 1:
var ajv = new Ajv({coerceTypes: true})
var schema = {
type: "object",
properties: {
foo: {type: "number"},
bar: {type: "boolean"},
},
required: ["foo", "bar"],
}
var data = {foo: "1", bar: "false"}
var validate = ajv.compile(schema)
console.log(validate(data)) // true
console.log(data) // { "foo": 1, "bar": false }
Example 2 (array coercions):
var ajv = new Ajv({coerceTypes: "array"})
var schema = {
properties: {
foo: {type: "array", items: {type: "number"}},
bar: {type: "boolean"},
},
}
var data = {foo: "1", bar: ["false"]}
var validate = ajv.compile(schema)
console.log(validate(data)) // true
console.log(data) // { "foo": [1], "bar": false }
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).
See Coercion rules for details.
Create Ajv instance.
Generate validating function and cache the compiled schema for future use.
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.
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.
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:
loadSchema returns a Promise that rejects).The function compiles schema and loads the first missing schema (or meta-schema) until all missing schemas are loaded.
You can asynchronously compile meta-schema by passing true as the second parameter.
See example in Asynchronous compilation.
Validate data using passed schema (it will be compiled and cached).
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.
Validation errors will be available in the errors property of Ajv instance (null if there were no errors).
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.
If the schema is asynchronous (has $async keyword on the top level) this method returns a Promise. See Asynchronous validation.
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.
Array of schemas can be passed (schemas should have ids), the second parameter will be ignored.
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.
Once the schema is added, it (and all the references inside it) can be referenced in other schemas and used to validate data.
Although addSchema does not compile schemas, explicit compilation is not required - the schema will be compiled when it is used first time.
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.
Please note: Ajv uses the method chaining syntax for all methods with the prefix add* and remove*.
This allows you to do nice things like the following.
var validate = new Ajv().addSchema(schema).addFormat(name, regex).getSchema(uri)
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).
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.
Validates schema. This method should be used to validate schemas rather than validate due to the inconsistency of uri format in JSON Schema standard.
By default this method is called automatically when the schema is added, so you rarely need to use it directly.
If schema doesn't have $schema property, it is validated against draft 6 meta-schema (option meta should not be false).
If schema has $schema property, then the schema with this id (that should be previously added) is used to validate passed schema.
Errors will be available at ajv.errors.
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.
Remove added/cached schema. Even if schema is referenced by other schemas it can be safely removed as dependent schemas have local references.
Schema can be removed using:
addSchemaIf no parameter is passed all schemas but meta-schemas will be removed and the cache will be cleared.
Add format to validate strings or numbers.
Strings are converted to RegExp.
Function should return validation result as true or false.
If object is passed it should have properties validate, compare and async:
formatMaximum/formatMinimum (defined in 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.true value if validate is an asynchronous function; in this case it should return a promise that resolves with a value true or false."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.Formats can be also added via formats option.
Add validation keyword to Ajv instance.
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.
Keyword must start with a letter, _ or $, and may continue with letters, numbers, _, $, or -.
It is recommended to use an application-specific prefix for keywords to avoid current and future name collisions.
Example Keywords:
"xyz-example": valid, and uses prefix for the xyz project to avoid name collisions."example": valid, but not recommended as it could collide with future versions of JSON Schema etc."3-example": invalid as numbers are not allowed to be the first character in a keywordKeyword definition is an object with the following properties:
false value used with "validate" keyword to not pass schematrue MUST be passed if keyword modifies datatrue/false to pre-define validation result, the result returned from validation function will be ignored. This option cannot be used with macro keywords.true value to support $data reference as the value of 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 code or validate function (the latter can be used in addition to compile or macro).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."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.compile, macro and code are mutually exclusive, only one should be used at a time. validate can be used separately or in addition to compile or macro to support $data reference.
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.
See User defined keywords for more details.
Returns keyword definition, false if the keyword is unknown.
Removes added or pre-defined keyword so you can redefine them.
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.
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.
Returns the text with all errors in a String.
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).
Defaults:
{
// strict mode options
strict: true,
allowMatchingProperties: false,
// validation and reporting options:
$data: false,
allErrors: false,
verbose: false,
$comment: false,
format: true,
formats: {},
unknownFormats: true,
schemas: {},
logger: undefined,
// referenced schema options:
missingRefs: true,
extendRefs: "ignore", // recommended 'fail'
loadSchema: undefined, // function(uri: string): Promise {}
// options to modify validated data:
removeAdditional: false,
useDefaults: false,
coerceTypes: false,
// advanced options:
meta: true,
validateSchema: true,
addUsedSchema: true,
inlineRefs: true,
passContext: false,
loopRequired: Infinity,
loopEnum: Infinity,
ownProperties: false,
multipleOfPrecision: false,
messages: true,
sourceCode: false,
processCode: undefined, // function (str: string, schema: object): string {}
cache: new Cache,
serialize: undefined
jsPropertySyntax: false, // deprecated
}
true (default) - use strict mode and throw an exception when any strict mode restrictions is violated."log" - log warning when any strict mode restriction is violated.false - ignore any strict mode restriction.schema and parentSchema) and validated data in errors (false by default).$comment keyword to a function. Option values:
false (default): ignore $comment keyword.true: log the keyword value to console.true (default) - validate added formats (see Formats).false - ignore all format keywords.addFormat method.addKeyword method.true (default) - if an unknown format is encountered the exception is thrown during schema compilation. If format keyword value is $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 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.addSchema(value, key) will be called for each schema in this object.console object that should have methods log, warn and error. See Error logging. Option values:
log, warn and error. If any of these methods is missing an exception will be thrown.false - logging is disabled.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)."ignore" - to log error during compilation and always pass validation."fail" - to log error and successfully compile schema but fail validation if this rule is checked.$ref is present in the schema. Option values:
"ignore" (default) - when $ref is used other keywords are ignored (as per JSON Reference standard). A warning will be logged during the schema compilation."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.true - validate all keywords in the schemas with $ref (the default behaviour in versions before 5.0.0).compileAsync method 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.addMetaSchema method. Option values:
false (default) - not to remove additional properties"all" - all additional properties are removed, regardless of additionalProperties keyword in schema (and no validation is made for them).true - only additional properties with additionalProperties keyword equal to false are removed."failing" - additional properties that fail schema validation will be removed (where additionalProperties keyword is false or schema).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. Option values:
false (default) - do not use defaultstrue - insert defaults by value (object literal is used)."empty" - in addition to missing or undefined, use defaults for properties and items that are equal to null or "" (an empty string).type keyword. See the example in Coercing data types and coercion rules. Option values:
false (default) - no type coercion.true - coerce scalar data types."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).$schema keyword. This default meta-schema MUST have $schema keyword.$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:
true (default) - if the validation fails, throw the exception."log" - if the validation fails, log error.false - skip schema validation.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.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.false - to not inline referenced schemas (they will be compiled as separate functions).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 keywords. By default this is Ajv instance.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.enum keyword is compiled into a single expression. In case of a very large number of allowed values it may result in a large validation function. Pass integer to set the number of values above which enum keyword will be validated in a loop.true only own enumerable object properties (i.e. found directly on the object rather than on its prototype) are iterated. Contributed by @mbroadst.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). 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).true by default. false can be passed when messages are generated outside of Ajv code (e.g. with ajv-i18n).sourceCode property to validating function (for debugging; this code can be different from the result of toString call).put(key, value), get(key), del(key) and clear().false to use schema itself as a key (e.g., if WeakMap used as a cache). By default fast-json-stable-stringify is used.true to report dataPath in errors as in v6, using JavaScript property syntax (e.g., ".prop[1].subProp"). By default dataPath in errors is reported as JSON pointer. This option is added for backward compatibility and is not recommended - this format is difficult to parse even in JS code.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, the returned promise is rejected with exception Ajv.ValidationError that has errors property.
Each error is an object with the following properties:
"/prop/1/subProp").messages set to false).verbose option).verbose option)verbose option).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".
Properties of params object in errors depend on the keyword that failed validation.
maxItems, minItems, maxLength, minLength, maxProperties, minProperties - property limit (number, the schema of the keyword).additionalItems - property limit (the maximum number of allowed items in case when items keyword is an array of schemas and additionalItems is false).additionalProperties - property additionalProperty (the property not used in properties and patternProperties keywords).dependencies - properties:
property (dependent property),missingProperty (required missing dependency - only the first one is reported currently)deps (required dependencies, comma separated list as a string),depsCount (the number of required dependencies).format - property format (the schema of the keyword).maximum, minimum - properties:
limit (number, the schema of the keyword),exclusive (boolean, the schema of exclusiveMaximum or exclusiveMinimum),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 "<", "<=", ">", ">=")multipleOf - property multipleOf (the schema of the keyword)pattern - property pattern (the schema of the keyword)required - property missingProperty (required property that is missing).propertyNames - property propertyName (an invalid property name).patternRequired (in ajv-keywords) - property missingPattern (required pattern that did not match any property).type - property type (required type(s), a string, can be a comma-separated list)uniqueItems - properties i and j (indices of duplicate items).const - property allowedValue pointing to the value (the schema of the keyword).enum - property allowedValues pointing to the array of values (the schema of the keyword).$ref - property ref with the referenced schema URI.oneOf - property passingSchemas (array of indices of passing schemas, null if no schema passes).User-defined keywords can define other keyword parameters.
A logger instance can be passed via logger option to Ajv constructor. 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.
log, warn, errorconst otherLogger = new OtherLogger()
const 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)
},
},
})
Ajv can be extended with plugins that add keywords, formats or functions to process generated code. When such plugin is published as npm package it is recommended that it follows these conventions:
If you have published a useful plugin please submit a PR to add it to the next section.
idn-hostname, idn-email, iri, iri-reference and duration).npm install
git submodule update --init
npm test
npm run build - compiles typescript to dist folder.
npm run watch - automatically compiles typescript when files in lib folder change
Please see Contributing guidelines
See https://github.com/ajv-validator/ajv/releases
Please note: Changes in version 6.0.0.
Please review and follow the Code of conduct.
Please report any unacceptable behaviour to ajv.validator@gmail.com - it will be reviewed by the project team.
Ajv is a part of Tidelift subscription - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.
FAQs
Another JSON Schema Validator
The npm package ajv receives a total of 41,770,532 weekly downloads. As such, ajv popularity was classified as popular.
We found that ajv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.