ajv - Another JSON Schema Validator

Currently the fastest JSON Schema validator for node.js and browser.

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

JSON Schema standard

ajv implements full JSON Schema draft 4 standard:

• all validation keywords (see JSON-Schema validation keywords)
• full support of remote refs (remote schemas have to be added with addSchema or compiled to be available)
• asynchronous loading of referenced schemas during compilation.
• support of circular dependencies between schemas
• 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)
• BETA: custom keywords supported starting from version 2.0.0, npm install ajv@2.0.0-beta.0 to use it

Currently ajv is the only validator that passes all the tests from JSON Schema Test Suite (according to json-schema-benchmark, apart from the test that requires that 1.0 is not an integer that is impossible to satisfy in JavaScript).

Performance

ajv generates code to turn JSON schemas into javascript functions that are efficient for v8 optimization.

Currently ajv is the fastest validator according to these benchmarks:

• json-schema-benchmark - 70% faster than the second place
• jsck benchmark - 20-190% faster
• z-schema benchmark
• themis benchmark

Install

npm install ajv

Usage

Try it in the node REPL: https://tonicdev.com/npm/ajv

The fastest validation call:

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 with less code

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

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

Using in browser

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 browserified bundle using bin/create-bundle script (thanks to siddo420).

Then you need to load ajv in the browser:

<script src="ajv.bundle.js"></script>

Now you can use it as shown above - require will be global and you can require('ajv').

Ajv was tested with these browsers:

Formats

The following formats are supported for string validation with "format" keyword:

• date: full-date from http://tools.ietf.org/html/rfc3339#section-5.6
• date-time: date-time from the same source. Both date and date-time validate ranges in full mode and only regexp in fast mode (see options).
• uri: full uri with optional protocol.
• email: email address.
• hostname: host name acording to http://tools.ietf.org/html/rfc1034#section-3.5
• ipv4: IP address v4.
• ipv6: IP address v6.
• regex: tests whether a string is a valid regular expression by passing it to RegExp constructor.

There are two modes of format validation: fast and full that affect all formats but ipv4 and ipv6. See Options for details.

You can add additional formats and replace any of the formats above using addFormat method.

You can find patterns used for format validation and the sources that were used in formats.js.

Defining custom keywords

Starting from version 2.0 (2.0.0-beta.0) ajv supports custom keyword definitions.

Disclaimer: The main drawback of extending JSON-schema standard with custom keywords is the loss of portability of your schemas - it may not be possible to support these custom keywords on some other platforms. Also your schemas may be more challenging to read for other people. If portability is important you may prefer using additional validation logic outside of JSON-schema rather than putting it inside your JSON-schema.

The advantages of using custom keywords are:

• they allow you keeping a larger portion of your validation logic in the schema
• they may make schema more expressive and less verbose
• they are fun to use and help keeping more people off the street

You can define custom keywords with addKeyword method. Keywords are defined on the ajv instance level - new instances will not have previously defined keywords automatically.

Ajv allows defining keywords in several ways:

• with validation function that will be called with keyword schema, data and, optionally, parent schema during validation (generally not recommended for performance reason, but can be useful to test your custom keyword ideas)
• with compilation function that will be called only once during schema compilation with keyword schema and, optionally, parent schema and should return schema validation function (in some cases it's the best approach with the performance cost of an extra function call during validation).
• NOT IMPLEMENTED: with schema macro function that will be called once before schema compilation with keyword schema and parent schema and should return another schema that will be applied to the data in addition to the original schema (allOf keyword is used to achieve that). In many cases it is the most efficient approach as it is relatively easy to implement and no extra function call happens during validation.
• NOT IMPLEMETED: with compilation function that should return code that will be inlined in the currently compiled schema. It can be more performance-efficient approach than macro expansion for some cases but it is the most difficult to use as it requires good understanding of Ajv schema compilation process.

Define keyword using validation function

Keyword can be defined with validation function that will be passed schema, data and parentSchema (if it has 3 arguments) at validation time and that should return validation result as boolean.

Example. draft5 constant keyword (that is equivalent to enum keyword with one item):

ajv.addKeyword('constant', { validate: validateConstant });

var schema = { "constant": 2 };
var validate = ajv.compile(schema);
console.log(validate(2)); // true
console.log(validate(3)); // false

var schema = { "constant": { "foo": "bar" } };
var validate = ajv.compile(schema);
console.log(validate({foo: 'bar'})); // true
console.log(validate({foo: 'baz'})); // false

function validateConstant(schema, data) {
  return typeof schema == 'object && schema !== null'
          ? deepEqual(schema, data)
          : schema === data;
}

This approach exists as a way to quickly test your keyword and is not recommended because of worse performance than compiling schemas.

Define keyword using "compilation" function

Keyword can also be defined using schema compilation function that is passed schema (and optionally parentSchema) and that should return validation function that will only be passed data.

Example. range and exclusiveRange keywords using compiled schema:

ajv.addKeyword('range', { type: 'number', compile: compileRange });

var schema = { "range": [2, 4], "exclusiveRange": true };
var 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

function compileRange(schema, parentSchema) {
  validateRangeSchema(schema, parentSchema);

  var min = schema[0];
  var max = schema[1];

  return parentSchema.exclusiveRange === true
          ? function (data) { return data > min && data < max; }
          : function (data) { return data >= min && data <= max; }
}

function validateRangeSchema(schema, parentSchema) {
  var schemaValid = Array.isArray(schema) && schema.length == 2
                    && typeof schema[0] == 'number'
                    && typeof schema[1] == 'number';
  if (!schemaValid) throw new Error('Invalid schema for range keyword, should be array of 2 numbers');

  var exclusiveRangeSchemaValid = parentSchema.exclusiveRange === undefined
                                  || typeof parentSchema.exclusiveRange == 'boolean';
  if (!exclusiveRangeSchemaValid) throw new Error('Invalid schema for exclusiveRange keyword, should be bolean');
}

Asynchronous compilation

Starting from version 1.3 ajv supports asynchronous compilation when remote references are loaded using supplied function. See compileAsync method and loadSchema option.

Example:

var ajv = Ajv({ loadSchema: loadSchema });

ajv.compileAsync(schema, function (err, validate) {
    if (err) return;
    var valid = validate(data);
});

function loadSchema(uri, callback) {
    request.json(uri, function(err, res, body) {
        if (err || res.statusCode >= 400)
            callback(err || new Error('Loading error: ' + res.statusCode));
        else
            callback(null, body);
    });
}

Filtering data

With option removeAdditional (added by andyscott) you can filter data during the validation.

This option modifies original object.

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 the option validateSchema is false, the schema will be validated against meta-schema and if schema is invalid the error will be thrown. See options.

.compileAsync(Object schema, Function callback)

Asyncronous version of compile method that loads missing remote schemas using asynchronous function in options.loadSchema. Callback will always be called with 2 parameters: error (or null) and validating function. Error will be not null in the following cases:

• missing schema can't be loaded (loadSchema calls callback with error).
• the schema containing missing reference is loaded, but the reference cannot be resolved.
• schema (or some referenced schema) is invalid.

The function compiles schema and loads the first missing schema multiple times, until all missing schemas are loaded.

See example in Asynchronous compilation.

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

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.

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

Add schema(s) to validator instance. From version 1.0.0 this method does not compile schemas (but it still validates them). Because of that change, 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.

.addMetaSchema(Object schema [, String key])

Adds meta schema 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 4 meta schema (http://json-schema.org/draft-04/schema and http://json-schema.org/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.

.validateSchema(Object schema) -> Boolean

Validates schema. This method should be used to validate schemas rather than validate due to the inconsistency of uri format in JSON-Schema standart.

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 4 meta-schema (option meta should not be false).

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

Errors will be available at ajv.errors.

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

Retrieve compiled schema previously added with addSchema by the key passed to addSchema or by its full reference (id). Returned validating function has schema property with the reference to the original schema.

.removeSchema(Object schema|String key|String ref)

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 key passed to addSchema, it's full reference (id) or using actual schema object that will be stable-stringified to remove schema from cache.

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

Strings are converted to RegExp.

Function should return validation result as true or false.

Custom formats can be also added via formats option.

.addKeyword(String keyword, Object definition)

Add custom validation keyword to ajv instance.

Keyword should be a valid JavaScript identifier.

Keyword should be different from all standard JSON schema keywords and different from previously defined keywords. There is no way to redefine keywords or remove keyword definition from the instance.

Keyword definition is an object with the following properties:

• type: optional string or array of strings with data type(s) that the keyword will apply to. If keyword is validating another type the validation function will not be called, so there is no need to check for data type inside validation function if type property is used.
• validate: validating function that will be called at validation time with keyword schema, data and parent schema (it will be passed only if the function has 3 arguments) and should return validation result as boolean. Validation function can return custom errors via errors property of itself. If validation result is false and errors are not returned, ajv will add default error with keyword property set to 'custom'. This aproach has the worst performance and is only recommending only for trying your custom keywords.
• compile: compiling function that will be called at schema compilation time with keyword schema and parent schema (it will be passed only if the function has 2 arguments) and should return validating function.
• macro (NOT IMPLEMENTED): macro function that that will be called before schema compilation with keyword schema and parent schema (it will be passed only if the function has 2 arguments) and should return another schema that will be applied on the save data level in addition to the original schema (allOf keyword us used to do it). The returned schema may contain the same or other custom keywords that will be recusively expanded until the final schema has no custom keywords defined with macros.
• inline (NOT IMPLEMENTED): compiling function that will be called at schema compilation time with keyword schema and parent schema (it will be passed only if the function has 2 arguments) and should return code (as string) that will be inlined in the currently compiled validation function.

validate, compile, macro and inline are mutually exclusive, only one should be used at a time.

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

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

Options

Defaults:

{
  allErrors:        false,
  removeAdditional: false,
  verbose:          false,
  format:           'fast',
  formats:          {},
  schemas:          {},
  meta:             true,
  validateSchema:   true,
  inlineRefs:       true,
  missingRefs:      true,
  loadSchema:       function(uri, cb) { /* ... */ cb(err, schema); },
  uniqueItems:      true,
  unicode:          true,
  beautify:         false,
  cache:            new Cache,
  jsonPointers:     false,
  i18n:             false,
  messages:         true
}

• allErrors: check all rules collecting all errors. Default is to return after the first error.
• removeAdditional: remove additional properties. Default is not to remove. If the option is 'all', then all additional properties are removed, regardless of additionalProperties keyword in schema (and no validation is made for them). If the option is true (or truthy), only additional properties with additionalProperties keyword equal to false are removed. If the option is 'failing', then additional properties that fail schema validation will be removed too (where additionalProperties keyword is schema).
• 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.
• schemas: an array or object of schemas that will be added to the instance. If the order is important, pass array. In this case schemas must have IDs in them. Otherwise the object can be passed - addSchema(value, key) will be called for each schema in this object.
• 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 http://json-schema.org/schema or http://json-schema.org/draft-04/schema or absent (draft-4 meta-schema will be used) or can be a reference to the schema previously added with addMetaSchema method. If the validation fails, the exception is thrown. Pass "log" in this option to log error instead of throwing exception. Pass false to skip schema validation.
• inlineRefs: by 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. Pass false to not inline referenced schemas (they will be compiled as separate functions). Pass integer number to limit the maximum number of keywords of the schema that will be inlined.
• missingRefs: by 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). Pass 'ignore' to log error during compilation and pass validation. Pass 'fail' to log error and successfully compile schema but fail validation if this rule is checked.
• loadSchema: asynchronous function that will be used to load remote schemas when the method compileAsync is used and some reference is missing (option missingRefs should not be 'fail' or 'ignore'). This function should accept 2 parameters: remote schema uri and node-style callback. See example in Asynchronous compilation.
• 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.
• cache: an optional instance of cache to store compiled schemas using stable-stringified schema as a key. For example, set-associative cache sacjs can be used. If not passed then a simple hash is used which is good enough for the common use case (a limited number of statically defined schemas). Cache should have methods put(key, value), get(key) and del(key).
• jsonPointers: Output dataPath using JSON Pointers instead of JS path notation.
• i18n: Support internationalization of error messages using ajv-i18n. See its repo for details.
• messages: Include human-readable messages in errors. true by default. messages: false can be added when internationalization (options i18n) is used.

Command line interface

Simple JSON-schema validation can be done from command line using ajv-cli package. At the moment it does not support referenced schemas.

Tests

npm install
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.

npm run build - compiles templates to dotjs folder.

npm run watch - automatically compiles templates when files in dot folder change

Changes history

See https://github.com/epoberezkin/ajv/releases

License

MIT