Skip to content

5.0.0
Compare
Choose a tag to compare
@epoberezkin epoberezkin released this 17 Apr 14:19
· 1701 commits to master since this release
5.0.0
8641c6b

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:

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:

Assets 2
Loading