ajv-formats

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.

An open question is how thoroughly to validate things like hostnames and IRIs where the syntax and semantics diverge. Writing a regex for hostnames checks the syntax (ie. contains only certain characters, there are multiple segments separated by . and the lengths of all segments and the total length). That won't catch obviously fake domains like unknown.unknown. This library goes a step further than just checking the syntax and also attempts to check the semantics as well. For example, when validating idn-hostname, this library will also check for a valid TLD.

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. Note that localhost is technically not a valid hostname.

duration

The string is checked against a regex.