ajv-formats

What is ajv-formats?

The ajv-formats package provides support for string formats in JSON Schema validation using the AJV validator. It includes various string formats for date-time, email, hostname, ipv4, ipv6, uri, uri-reference, uuid, and more, which can be used to validate data against specific format requirements.

What are ajv-formats's main functionalities?

Date-time format validation

Validates that a string is a valid date-time representation according to the format specified in the JSON Schema.

{"type":"string","format":"date-time"}

Email format validation

Validates that a string is a valid email address.

{"type":"string","format":"email"}

URI format validation

Validates that a string is a valid URI.

{"type":"string","format":"uri"}

UUID format validation

Validates that a string is a valid UUID.

{"type":"string","format":"uuid"}

Other packages similar to ajv-formats

jsonschema

The jsonschema package is a JSON Schema validator that also provides format validation. It supports similar functionalities to ajv-formats but is implemented in a different way and may have different performance characteristics.

tv4

tv4 is a tiny validator for JSON Schema v4. Like ajv-formats, it can validate formats specified in a JSON Schema, but it is less feature-rich and not as actively maintained as AJV.

joi

Joi is a powerful schema description language and data validator for JavaScript. Unlike ajv-formats, Joi does not use JSON Schema but instead provides its own schema definition language, which can be more expressive and easier to use for some developers.

README

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.