ajv

by epoberezkin

epoberezkin / ajv

The fastest JSON Schema Validator. Supports draft-04/06/07

0 Stars 0 Forks Last release: Not found MIT License 1.9K Commits 146 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Ajv logo

Ajv: Another JSON Schema Validator

The fastest JSON Schema validator for Node.js and browser. Supports draft-06/07 (draft-04 is supported in v6).

Build Status npm npm (beta) npm downloads Coverage Status Gitter GitHub Sponsors

Using version 7 (beta)

Ajv version 7.0.0-beta.0 is released with these changes:

  • to reduce the mistakes in JSON schemas and unexpected validation results, strict mode is added - it prohibits ignored or ambiguous JSON Schema elements.
  • to make code injection from untrusted schemas impossible, code generation is fully re-written to be safe.
  • to simplify Ajv extensions, the new keyword API that is used by pre-defined keywords is available to user-defined keywords - it is much easier to define any keywords now, especially with subschemas.
  • schemas are compiled to ES6 code (ES5 code generation is supported with an option).
  • the support for JSON-Schema draft-04 is removed - if you have schemas using "id" attributes you have to replace them with "\$id" (or continue using version 6 that will be supported until 02/28/2021).
  • all formats are separated to ajv-formats package - they have to be explicitely added if you use them.
  • to improve reliability and maintainability the code is migrated to TypeScript.

See release notes for the details.

To install the new version:

npm install [email protected]

See Getting started for code example.

Please note: use Ajv v6 if you need draft-04 support - v7 does NOT support it.

Contents

Ajv v7 beta is released

Ajv version 7.0.0-beta.0 is released with these changes:

  • to reduce the mistakes in JSON schemas and unexpected validation results, strict mode is added - it prohibits ignored or ambiguous JSON Schema elements.
  • to make code injection from untrusted schemas impossible, code generation is fully re-written to be safe.
  • to simplify Ajv extensions, the new keyword API that is used by pre-defined keywords is available to user-defined keywords - it is much easier to define any keywords now, especially with subschemas.
  • schemas are compiled to ES6 code (ES5 code generation is supported with an option).
  • to improve reliability and maintainability the code is migrated to TypeScript.

Please note:

  • the support for JSON-Schema draft-04 is removed - if you have schemas using "id" attributes you have to replace them with "\$id" (or continue using version 6 that will be supported until 02/28/2021).
  • all formats are separated to ajv-formats package - they have to be explicitely added if you use them.

See release notes for the details.

To install the new version:

npm install [email protected]

See Getting started with v7 for code example.

Mozilla MOSS grant and OpenJS Foundation

   

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.

Please sponsor Ajv development

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.

Open Collective sponsors

Performance

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:

performance

Features

Install

npm install ajv

To install version 7 beta:

npm install [email protected]

Getting started

Try it in the Node.js REPL: https://runkit.com/npm/ajv

In JavaScript:

// Node.js require:
const Ajv = require("ajv")
// or ESM/TypeScript import
import Ajv from "ajv"

const ajv = new Ajv() // options can be passed, e.g. {allErrors: true} const validate = ajv.compile(schema) const valid = validate(data) if (!valid) console.log(validate.errors)

In TypeScript:

import Ajv, {JSONSchemaType, DefinedError} from "ajv"

const ajv = new Ajv()

type MyData = {foo: number}

// optional schema type annotation for schema to match MyData type const schema: JSONSchemaType = { type: "object", properties: { foo: {type: "number", minimum: 0}, }, required: ["foo"], additionalProperties: false, }

// validate is a type guard for MyData - type is inferred from schema type const validate = ajv.compile(schema)

// or, if you did not use type annotation for the schema, // type parameter can be used to make it type guard: // const validate = ajv.compile(schema)

const data: any = {foo: 1}

if (validate(data)) { // data is MyData here console.log(data.foo) } else { // The type cast is needed to allow user-defined keywords and errors // You can extend this type to include your error types as needed. for (const err of validate.errors as DefinedError[]) { switch (err.keyword) { case "minimum": // err type is narrowed here to have "minimum" error params properties console.log(err.params.limit) break // ... } } }

See this test for an advanced example, API reference and Options for more details.

Ajv compiles schemas to functions and caches them in all cases (using schema itself as a key for Map) 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

Using in browser

See Content Security Policies to decide the best approach how to use Ajv in the browser.

Whether you use Ajv or compiled schemas, it is recommended that you bundle them together with your code.

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:


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.

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

Command line interface

CLI is available as a separate npm package ajv-cli. It supports:

  • compiling JSON Schemas to test their validity
  • BETA: generating standalone module exporting a validation function to be used without Ajv (using ajv-pack)
  • migrate schemas to draft-07 (using json-schema-migrate)
  • validating data file(s) against JSON Schema
  • testing expected validity of data against JSON Schema
  • referenced schemas
  • user-defined meta-schemas
  • files in JSON, JSON5, YAML, and JavaScript format
  • all Ajv options
  • reporting changes in data after validation in JSON-patch format

Plugins

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:

  • it exports a function
  • this function accepts ajv instance as the first parameter and returns the same instance to allow chaining
  • this function can accept an optional configuration as the second parameter

Youcan import

Plugin
interface from ajv if you use Typescript.

If you have published a useful plugin please submit a PR to add it to the next section.

Related packages

  • ajv-bsontype - plugin to validate mongodb's bsonType formats
  • ajv-cli - command line interface
  • ajv-formats - formats defined in JSON Schema specification.
  • ajv-errors - plugin for defining error messages in the schema
  • ajv-i18n - internationalised error messages
  • ajv-istanbul - plugin to instrument generated validation code to measure test coverage of your schemas
  • ajv-keywords - plugin with additional validation keywords (select, typeof, etc.)
  • ajv-merge-patch - plugin with keywords $merge and $patch
  • ajv-pack - produces a compact module exporting validation functions
  • ajv-formats-draft2019 - format validators for draft2019 that aren't included in ajv-formats (ie.
    idn-hostname
    ,
    idn-email
    ,
    iri
    ,
    iri-reference
    and
    duration
    ).

Some packages using Ajv

  • webpack - a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser
  • jsonscript-js - the interpreter for JSONScript - scripted processing of existing endpoints and services
  • osprey-method-handler - Express middleware for validating requests and responses based on a RAML method object, used in osprey - validating API proxy generated from a RAML definition
  • har-validator - HTTP Archive (HAR) validator
  • jsoneditor - a web-based tool to view, edit, format, and validate JSON http://jsoneditoronline.org
  • JSON Schema Lint - a web tool to validate JSON/YAML document against a single JSON Schema http://jsonschemalint.com
  • objection - SQL-friendly ORM for Node.js
  • table - formats data into a string table
  • ripple-lib - a JavaScript API for interacting with Ripple in Node.js and the browser
  • restbase - distributed storage with REST API & dispatcher for backend services built to provide a low-latency & high-throughput API for Wikipedia / Wikimedia content
  • hippie-swagger - Hippie wrapper that provides end to end API testing with swagger validation
  • react-form-controlled - React controlled form components with validation
  • rabbitmq-schema - a schema definition module for RabbitMQ graphs and messages
  • @query/schema - stream filtering with a URI-safe query syntax parsing to JSON Schema
  • chai-ajv-json-schema - chai plugin to us JSON Schema with expect in mocha tests
  • grunt-jsonschema-ajv - Grunt plugin for validating files against JSON Schema
  • extract-text-webpack-plugin - extract text from bundle into a file
  • electron-builder - a solution to package and build a ready for distribution Electron app
  • addons-linter - Mozilla Add-ons Linter
  • gh-pages-generator - multi-page site generator converting markdown files to GitHub pages
  • ESLint - the pluggable linting utility for JavaScript and JSX

Tests

npm install
git submodule update --init
npm test

Contributing

npm run build
- compiles typescript to dist folder.

npm run watch
- automatically compiles typescript when files in lib folder change

Please see Contributing guidelines

Changes history

See https://github.com/ajv-validator/ajv/releases

Please note: Changes in version 7.0.0-beta

Version 6.0.0.

Code of conduct

Please review and follow the Code of conduct.

Please report any unacceptable behaviour to [email protected] - it will be reviewed by the project team.

Security contact

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.

Open-source software support

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.

License

MIT

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.