ajv

Changed order of type validation - "type" keyword is now validated before keywords that apply to all types.

More comprehencive uri-reference format in {format: "full"} mode.

Rename format uri-ref to uri-reference Cross-platform scripts Update draft-6 meta-schema

Support $id from draft-06. Option schemaId determining whether $id, id or both are used. See Options Format "regex" is changed to prohibit \Z anchor. Format "uri" is changed to only allow absolute URIs, relative URIs are supported with "uri-ref". Run draft-06 tests from JSON-Schema-Test-Suite in addition to draft-04 tests.

Support custom formats for numbers (#291) Option ownProperties supports all keywords (#197). See Options. Improve support of custom keywords with $data option.

Also see 5.0.1-beta.0 about the migration from 4.x.x

Improve error handling (#380, #394) Improve webpack support (#403)

Option serialize to replace json-stable-stringify with another function to serialise schemas. Support deprecated patternGroups without draft-06 meta-schema. Log warning instead of throwing exception when option meta: false is used without validateSchema: false.

Same as 4.11.0 Also see 5.0.1-beta.0

If you are migrating from 4.x.x also see 5.0.0-beta.1 and Migration section below

Changes

Keyword changes

Support for all keywords included in draft 6 (it is not published yet and can change).

• const (previously available as constant). To simplify migration you can define an alias constant as a custom macro keyword:

    ajv.addKeyword('constant', { macro: x => ({ const: x }) });
  

• contains. It is re-implemented as a standard keyword, if none of the items is valid, errors for all items will be reported now.

• NEW propertyNames keyword added (previously it was a part of ajv-keywords package). It allows to validate all property names rather than values.

• exclusiveMaximum/Minimum in draft 6 must be numbers, Ajv supports boolean form too for backwards compatibility.

Moved/deprecated:

• switch, patternRequired and formatMinimum/Maximum moved to ajv-keywords (^2.0.0-beta).
• patternGroups is deprecated, it can be still used with option patternRequired.

Draft 6 support

• Support for boolean schemas: wherever a schema is required, true/false can be used in order to always pass/fail validation.
• Meta-schema - by default Ajv adds backwards compatible draft 6 meta-schema. Its URI used in Ajv is http://json-schema.org/draft-06/schema# (it can change when draft 6 is published).

If your $schema keyword points to draft 4 or v5 meta-schema you need to add it manually:

ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));
// or
ajv.addMetaSchema(require('ajv/lib/refs/json-schema-v5.json'));

Options

• v5 is no longer used, for $data reference support use option $data
• beautify: true is no longer supported.
• processCode: function() {} can be used to beautify/transpile generated code. See Options

Asynchronous validation

• Auto-detection of async mode and transpile option support require ajv-async package.
• Default async mode is "co*" (co-wrapped generator functions).
• If you need to transpile code without ajv-async package, you can pass transpilation function in processCode option. See Options.
• In case of validation success, returned Promise resolves with validated data to simplify chaining (previously it resolved with true).

Related packages

Compatible versions are:

• ajv-keywords: ^2.0.0-beta
• ajv-merge-patch: ^3.0.0-beta
• ajv-i18n: ^2.0.0-beta

Migration from 4.x.x

If you use draft-04 schemas

var ajv = new Ajv({
  meta: false, // optional, to prevent adding draft-06 meta-schema
  extendRefs: true, // optional, current default is to 'fail', spec behaviour is to 'ignore'
  unknownFormats: 'ignore',  // optional, current default is true (fail)
  // ...
});

var metaSchema = require('ajv/lib/refs/json-schema-draft-04.json');
ajv.addMetaSchema(metaSchema);
ajv._opts.defaultMeta = metaSchema.id;

// optional, using unversioned URI is out of spec, see https://github.com/json-schema-org/json-schema-spec/issues/216
ajv._refs['http://json-schema.org/schema'] = 'http://json-schema.org/draft-04/schema';

// Optionally you can also disable keywords defined in draft-06
ajv.removeKeyword('propertyNames');
ajv.removeKeyword('contains');
ajv.removeKeyword('const');

If you use schemas requiring v5 mode of Ajv

var ajv = new Ajv({
  $data: true,
  patternGroups: true,
  meta: false, // optional, to prevent adding draft-06 meta-schema
  extendRefs: true, // optional, current default is to 'fail', spec behaviour is to 'ignore'
  unknownFormats: 'ignore',  // optional, current default is true (fail)
  // ...
});

ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));
ajv._refs['http://json-schema.org/schema'] = 'http://json-schema.org/draft-04/schema'; // optional, using unversioned URI is out of spec
var metaSchema = require('ajv/lib/refs/json-schema-v5.json');
ajv.addMetaSchema(metaSchema);
ajv._opts.defaultMeta = metaSchema.id;

// optional - to avoid changing the schemas
ajv.addKeyword('constant', { macro: x => ({ const: x }) }); // this keyword is renamed to const in draft-06
// you need to use version "^2.0.0-beta" of ajv-keywords
require('ajv-keywords')(ajv, ['switch', 'patternRequired', 'formatMinimum', 'formatMaximum']);

// Optionally you can also disable propertyNames keyword defined in draft-06
ajv.removeKeyword('propertyNames');

This release is fully backward compatible, but it may require either migrating your schemas (recommended, e.g. using "migrate" command of ajv-cli) or changing your code that uses Ajv.

You can still use draft-04 and v5 schemas with this release (see Migration guide below).

The changes below are based on 4.11.7 version.

JSON-Schema draft-06 support

• Support for boolean schemas: wherever a schema is required, true/false can be used in order to always pass/fail validation.
• $id keyword is used as schema URI (previously id).
• exclusiveMaximum and exclusiveMinimum keywords must be numbers (previously boolean).
• additional validation keywords: const, contains, propertyNames.
• additional formats: uri-reference, uri-template.

See Internet drafts: JSON Schema, JSON Schema Validation.

Migrating from Ajv 4.x.x

Migrate your schemas

It is a recommended approach.

Required changes

• replace id with $id
• update $schema
• replace boolean form of exclusiveMaximum/Minimum with numeric form
• replace Ajv v5 constant with const

Optional changes

• replace enum with a single allowed value with const
• replace empty schemas with true
• replace schemas {"not":{}} with false

You can use "migrate" command of ajv-cli to make these changes to your schemas.

If you need to continue using draft-04 schemas

var ajv = new Ajv({
  meta: false, // optional, to prevent adding draft-06 meta-schema
  extendRefs: true, // optional, current default is to 'fail', spec behaviour is to 'ignore'
  unknownFormats: 'ignore',  // optional, current default is true (fail)
  // ...
});

var metaSchema = require('ajv/lib/refs/json-schema-draft-04.json');
ajv.addMetaSchema(metaSchema);
ajv._opts.defaultMeta = metaSchema.id;

// optional, using unversioned URI is out of spec, see https://github.com/json-schema-org/json-schema-spec/issues/216
ajv._refs['http://json-schema.org/schema'] = 'http://json-schema.org/draft-04/schema';

// Optionally you can also disable keywords defined in draft-06
ajv.removeKeyword('propertyNames');
ajv.removeKeyword('contains');
ajv.removeKeyword('const');

If you need to continue using schemas requiring v5 mode of Ajv

var ajv = new Ajv({
  $data: true,
  patternGroups: true,
  meta: false, // optional, to prevent adding draft-06 meta-schema
  extendRefs: true, // optional, current default is to 'fail', spec behaviour is to 'ignore'
  unknownFormats: 'ignore',  // optional, current default is true (fail)
  // ...
});

ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));
ajv._refs['http://json-schema.org/schema'] = 'http://json-schema.org/draft-04/schema'; // optional, using unversioned URI is out of spec
var metaSchema = require('ajv/lib/refs/json-schema-v5.json');
ajv.addMetaSchema(metaSchema);
ajv._opts.defaultMeta = metaSchema.id;

// optional - to avoid changing the schemas
ajv.addKeyword('constant', { macro: x => ({ const: x }) }); // this keyword is renamed to const in draft-06
// you need to use version "^2.0.0" of ajv-keywords
require('ajv-keywords')(ajv, ['switch', 'patternRequired', 'formatMinimum', 'formatMaximum']);

// Optionally you can also disable propertyNames keyword defined in draft-06
ajv.removeKeyword('propertyNames');

Changes

Validation keywords

Moved/deprecated:

• switch, patternRequired and formatMinimum/Maximum moved to ajv-keywords (^2.0.0).
• patternGroups is deprecated, it can be still used with option patternRequired.

Formats

• Support custom formats for numbers (#291).
• Format "regex" is changed to prohibit \Z anchor.
• Format "uri" is changed to only allow absolute URIs, relative URIs are supported with "uri-reference".
• Added format "url" (WHATWG URL specification).

Methods

• Methods are no longer bound to Ajv instances (#232).
• compileAsync method returns Promise and supports async loading of meta-schemas (#249, #334).

Options

• schemaId determining whether $id, id or both are used.
• $data for $data reference support.
• ownProperties supports all keywords (#197).
• serialize to replace json-stable-stringify with another function to serialise schemas.
• Log warning instead of throwing exception when option meta: false is used without validateSchema: false.
• processCode: function() {} can be used to beautify/transpile generated code.
• beautify: true is no longer supported.
• v5 is no longer used.

Option defaults changed:

• extendRefs: "ignore" - when $ref is used other keywords are ignored (was true) (#294).
• sourceCode: false - do not store source code of validation functions (was true) (#309).
• unknownFormats: true - fail schema compilation (was "ignore") (#324).

Asynchronous validation

• Auto-detection of async mode and transpile option support require ajv-async package.
• Default async mode is "co*" (co-wrapped generator functions).
• If you need to transpile code without ajv-async package, you can pass transpilation function in processCode option. See Options.
• In case of validation success, returned Promise resolves with validated data to simplify chaining (previously it resolved with true).

Other

• Ajv.MissingRefError class is used to throw missing $ref exception.
• Typings are updated - typescript 2.0 is required.
• Errors are logged using console.warn and console.error (#265).
• Improve error handling (#380, #394).
• Improve webpack support (#403).

Related packages

Compatible versions are:

• ajv-keywords: ^2.0.0
• ajv-i18n: ^2.0.0
• ajv-merge-patch: ^3.0.0

Ajv.MissingRefError class is used to throw missing $ref exception Typings are updated - typescript 2.0 is required now

Also see 5.0.0-beta.0

Methods are no longer bound to Ajv instances (#232). compileAsync method returns Promise and supports async loading of meta-schemas (#249, #334). Errors are logged using console.warn and console.error (#265). If async option is not specified, es7 native async functions are used as the primary option (if available)(#338), see Asynchronous validation. Option defaults changed (see Options):

• extendRefs: "fail" - fail schema compilation (#294).
• sourceCode: false - do not store source code of validation functions (#309).
• unknownFormats: true - fail schema compilation (#324).

Defaults in version 4.x.x:

{
  extendRefs: true,
  sourceCode: true,
  unknownFormats: 'ignore'
}

Custom keywords enhancements:

• allow hyphens in keyword names.
• option modifying: true in keyword definition to support keywords that change data (#392).
• option valid: true/false in keyword definition to pre-define validation result - it allows to simplify generated code in cases when keywords are used only for side-effects (#393).

Method getKeyword to return keyword definition. Method removeKeyword to remove custom or pre-defined keyword. See API. Fix for webpack warnings for optional dependencies (#117, #325).

Support undefined, RegExp and Date instances in uniqueItems keyword (#342).

Option unknownFormats to fail schema compilation if unknown format is used or fail validation if unknown format is in v5 $data reference (#310) Support for generating standalone module exporting a validation function to be used without Ajv (using ajv-cli)

Fixes:

• replace eval with Function constructor
• $data: allow null as schema value in keywords that support $data reference (#305)
• $ref: support escaped characters (#311)
• format hostname: allow segments of hostnames to start with digit (#312)
• extendRef option: do NOT log warning if explicitely set to true (#303)

Reduce memory utilisation by compiled validation functions (#293, @rf):

• replace eval with new Function (to reduce the size of scope variables of closures)
• option sourceCode: false to optionally not store the generated code in the property of validating functions

Support absolute JSON-pointers in $data references (#285, #289, @HotelDon). allowedValues param in "enum" keyword error (#282). Use Ajv bundle with webpack (#117, #288, @donaldpipowitch). Pass schema compilation context as the 3rd parameter to compile and macro custom keyword functions (#280). Pass root data as the 5th parameter to validation functions (including validate custom keyword function).

Improved support of references:

• $ref to schema fragment in methods validate and getSchema (#47).
• $ref with protocol-relative URIs (#277)

Option extendRefs to disable validation of other keywords when $ref is present in the schema. Support validating schemas against themselves (to allow meta-schemas where id is the same as $schema, e.g. JSON hyper meta-schema).

Coerce between scalar data and arrays with option coerceTypes: 'array' (#158, @willfarrell). See Coercing data types.

Custom keywords:

• support $data reference (#146)
• meta schema for custom keyword schemas (#230)

Improved support for mutually recursive references (#210, #240) Support control characters in JSON properties (#226)