One of the fastest JSON Schema validators for node.js and browser.
It uses precompiled doT templates to generate super-fast validating functions.
ajv implements full JSON Schema draft 4 standard:
- all validation keywords
- full support of remote refs (remote schemas have to be added with
addSchemaor 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).
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.
npm install ajv
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.
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:
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
dateanddate-timevalidate ranges infullmode and only regexp infastmode (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 fomat 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.
Create ajv instance.
All the instance methods below are bound to the instance, so they can be used without the instance.
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.
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).
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.
Version 1.0 will only compile schemas when they are used the first time. The order of addition in this version is not important and it supports circular references. Try it from the branch if you need them and please report any issues.
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.
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.
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.
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.
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.
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).
- 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
falsenot 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
addFormatmethod. - 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).
$schemaproperty 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. Passfalseto skip schema validation. - missingRefs: by default if the reference cannot be resolved during compilation the exception is thrown. 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.
- uniqueItems: validate
uniqueItemskeyword (true by default). - unicode: calculate correct length of strings with unicode pairs (true by default). Pass
falseto use.lengthof 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-beautifyto use this option.trueor 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)andget(key).
npm install
git submodule update --init
npm test
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
bin/git-hook to install symbolic link to pre-commit hook that will compile templates and run tests.
Errors for "required" keyword validation include missing properties
Better references resolution in schemas without IDs
cache option and removeSchema method
doT is no longer a run-time dependency
ajv can be used in the browser (with browserify)
Schemas are validated against meta-schema before compilation
Custom formats support.
Errors are set to null if there are no errors (previously empty array).