ajv

What is ajv?

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.

What are ajv's main functionalities?

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);
});"}

Other packages similar to ajv

joi

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.

tv4

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.

jsonschema

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.

README

ajv - Another JSON Schema Validator

One of the fastest JSON Schema validators for node.js and browser.

It uses precompiled doT templates to generate super-fast validating functions.

JSON Schema standard

ajv implements full JSON Schema draft 4 standard:

• all validation keywords
• full support of remote refs (remote schemas have to be added with addSchema or compiled to be available)
• correct string lengths for strings with unicode pairs (can be turned off)
• formats defined by JSON Schema draft 4 standard and custom formats (can be turned off)

ajv passes all the tests from JSON Schema Test Suite (apart from the one that requires that 1.0 is not an integer).

Benchmarks

Benchmark of the test suite - json-schema-benchmark.

Same benchmark run on faster CPU with node 0.12.

Benchmark of individual test cases by z-schema.

Install

npm install ajv

Usage

var Ajv = require('ajv');
var ajv = Ajv(); // options can be passed
var validate = ajv.compile(schema);
var valid = validate(data);
if (!valid) console.log(validate.errors);

or

// ...
var valid = ajv.validate(schema, data);
if (!valid) console.log(ajv.errors);
// ...

or

// ...
ajv.addSchema(schema, 'mySchema');
var valid = ajv.validate('mySchema', data);
if (!valid) console.log(ajv.errorsText());
// ...

ajv compiles schemas to functions and caches them in all cases (using stringified schema as a key - using json-stable-stringify), so that the next time the same schema is used (not necessarily the same object instance) it won't be compiled again.

API

Ajv(Object options) -> Object

Create ajv instance.

All the instance methods below are bound to the instance, so they can be used without the instance.

.compile(Object schema) -> Function<Object data>

Generate validating function and cache the compiled schema for future use.

Validating function returns boolean and has properties errors with the errors from the last validation (null if there were no errors) and schema with the reference to the original schema.

Unless options validateSchema is false, the schema will be validated against meta-schema and if schema is invalid the errors will be logged. See options.

.validate(Object schema|String key|String ref, data) -> Boolean

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).

.addSchema(Array<Object>|Object schema [, String key]) -> Function|Array<Function>

Add and compile schema(s). It does the same as .compile with two differences:

• 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 added it and all the references inside it can be referenced in other schemas and used to validate data.

In the current version all the referenced schemas should be added before the schema that uses them is compiled, so the circular references are not supported.

By default schema is validated against meta-schema before it is compiled and if the schema does not pass validation the exception is thrown. This behaviour is controlled by validateSchema option.

.validateSchema(Object schema) -> Boolean

Validates schema.

If schema doesn't have $schema property it is validated against draft 4 meta-schema (option meta should not be false).

If schema has $schema property than the schema with this id (should be previously added) is used to validate passed schema.

Errors are available at ajv.errors.

.getSchema(String key) -> Function<Object data>

Retrieve compiled schema previously added with addSchema. Validating function has schema property with the reference to the original schema.

.addFormat(String name, String|RegExp|Function format)

Add custom format to validate strings. It can also be used to replace pre-defined formats for ajv instance.

Strins be converted to RegExp.

Function should return validation result as true or false.

Custom formats can be also added via formats option.

.errorsText([Array errors [, Object options]]) -> String

Returns the text with all errors in a String. Options can have these properties:

• separator: string used to separate errors, ", " is used by default.
• dataVar: the variable name that dataPaths are prefixed with, "data" by default.

Options

• allErrors: check all rules collecting all errors. Default is to return after the first error.
• verbose: include the reference to the part of the schema and validated data in errors (false by default).
• format: formats validation mode ('fast' by default). Pass 'full' for more correct and slow validation or false not to validate formats at all. 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.
• formats: an object with custom formats. Keys and values will be passed to addFormat method.
• meta: add meta-schema so it can be used by other schemas (true by default).
• _validateSchema: validate added/compiled schemas against meta-schema (true by default). $schema property in the schema can either be absent (draft-4 meta-schema will be used) or can be a reference to any previously added schema. If the validation fails, the exception is thrown. Pass "log" in this option to log error instead of throwing exception.
• uniqueItems: validate uniqueItems keyword (true by default).
• unicode: calculate correct length of strings with unicode pairs (true by default). Pass false to use .length of strings that is faster, but gives "incorrect" lengths of strings with unicode pairs - each unicode pair is counted as two characters.
• beautify: format the generated function with js-beautify (the validating function is generated without line-breaks). npm install js-beautify to use this option. true or js-beautify options can be passed.

Tests

git submodule update --init
npm test

Contributing

All validation functions are generated using doT templates in dot folder. Templates are precompiled so doT is not a run-time dependency.

bin/compile_dots to compile templates to dotjs folder

bin/watch_dots to automatically compile templates when files in dot folder change

There is pre-commit hook that runs compile_dots and tests.

Changes history

0.5.2

doT is no longer a run-time dependency

ajv can be used in the browser (with browserify)

0.5.0

Schemas are validated against meta-schema before compilation

0.4.1

Custom formats support.

0.4.0

Errors are set to null if there are no errors (previously empty array).