ajv-formats

Plugin for AJV that adds support for additional international formats and formats added in draft2019.

Currently, iri, iri-reference, idn-email, idn-hostname, and duration formats are supported. duration was added in draft 2019.

Installation

npm install ajv-formats

Usage

The default export is an apply function that patches an existing instance of ajv.

const Ajv = require('ajv');
const apply = require('ajv-formats');
const ajv = new Ajv();
apply(ajv); // returns ajv instance, allowing chaining

let schema = {
  type: 'string',
  format: 'idn-email',
};
ajv.validate(schema, 'квіточка@пошта.укр'); // returns true

The apply function also accepts a second optional parameter to specify which formats to add to the ajv instance.

const Ajv = require('ajv');
const apply = require('ajv-formats');
const ajv = new Ajv();

// Install only the idn-email and iri formats
apply(ajv, { formats: ['idn-email', 'iri'] });

The module also provides an alternate entrypoint ajv-formats/formats that works with the ajv constructor to add the formats to new instances.

const Ajv = require('ajv');
const formats = require('ajv-formats/formats');
const ajv = new Ajv({ formats });

let schema = {
  type: 'string',
  format: 'idn-email',
};
ajv.validate(schema, 'квіточка@пошта.укр'); // returns true

Using the ajv-formats/formats entry point also allows cherry picking formats. Note the approach below only works for formats that don't contain a hypen - in the name. This approach may yield smaller packed bundles since it allows tree-shaking to remove unwanted validators and related dependencies.

const Ajv = require('ajv');
const { duration, iri } = require('ajv-formats/formats');
const ajv = new Ajv({ formats: { duration, iri } });

International formats

The library also provides an idn export to load only the international formats (ie. iri, iri-reference, idn-hostname and idn-email).

const Ajv = require('ajv');
const formats = require('ajv-formats/idn');
const ajv = new Ajv({ formats });

Formats

iri

The string is parsed with 'uri-js' and the scheme is checked against the list of known IANA schemes. If it's a 'mailto' schemes, all of the to: addresses are validated, otherwise we check there IRI includes a path and is an absolute reference.

iri-reference

All valid IRIs are valid. Fragments must have a valid path and of type "relative", "same-document" or "uri". If there is a scheme, it must be valid.

Validating a IRI references is challenging since the syntax is so permissive. Basically, any URL-safe string is a valid IRI syntactically. I struggled to find negative test cases when writing the unit tests for IRI-references. Consider:

• google.com is NOT a valid IRI because it does not include a scheme.
• file.txt is a valid IRI-reference
• /this:that is a valid IRI-reference
• this:that is a NOT a valid IRI-reference

idn-email

isemail is used to check the validity of the email.

idn-hostname

The hostname is converted to ascii with punycode and checked for a valid tld.

duration

The string is checked against a regex.