ajv-formats

To use JSON Schema formats with an Ajv instance, import addFormats and call it passing your Ajv instance as the first argument. This registers the standard set of formats with your validator.

ESM/TypeScript

import Ajv from "ajv"
import addFormats from "ajv-formats"

const ajv = new Ajv()
addFormats(ajv)

Node.js (CommonJS)

const Ajv = require("ajv")
const addFormats = require("ajv-formats")

const ajv = new Ajv()
addFormats(ajv)

You can pass an options object as the second argument to addFormats(ajv, options) to control which formats are loaded and how they behave.

1. Select specific formats

Pass an array of format names to only add those specific formats to the Ajv instance.

addFormats(ajv, ["date", "time"])

2. Configure validation mode and keywords

Use the mode and keywords options.

• mode: Set to "fast" to use simplified regular expressions and skip range validation for certain formats (date, time, date-time, iso-time, iso-date-time, uri, uri-reference, email). This improves performance but reduces validation strictness.
• keywords: Set to true to enable the comparison keywords (formatMinimum, etc.).

Example: Fast mode with specific formats and keywords enabled

addFormats(ajv, { mode: "fast", formats: ["date", "time"], keywords: true })

The formatsPlugin accepts two types of options: a simple array of format names or a FormatOptions object.

FormatOptions

• mode: Either "fast" or "full". "fast" uses a subset of formats optimized for performance, while "full" includes the complete set.
• formats: An array of FormatName to specifically include.
• keywords: A boolean (defaults to true). If true, it registers formatLimit keywords (like formatMaximum, formatMinimum, etc.) on the ajv instance.

export interface FormatOptions {
  mode?: FormatMode
  formats?: FormatName[]
  keywords?: boolean
}

export type FormatsPluginOptions = FormatName[] | FormatOptions

The formatsPlugin is the primary entrypoint for adding format validation to an Ajv instance. It can be used as a plugin by passing it to ajv.addFormat or by calling it directly with an Ajv instance.

By default, it adds all available formats and enables formatLimit keywords. You can customize the plugin to only include specific formats, switch between fast and full modes, or disable the automatic addition of limit keywords.

import Ajv from "ajv";
import formatsPlugin from "ajv-formats";

const ajv = new Ajv();

// Basic usage: adds all formats and limit keywords
formatsPlugin(ajv);

// Usage with specific formats
formatsPlugin(ajv, {
  formats: ["email", "date-time"],
  mode: "fast"
});

The fastFormats object provides a subset of the full formats optimized for speed. It uses simpler regular expressions for formats like date, time, email, and uri. This is ideal for performance-critical applications where strict standard compliance (e.g., complex RFC edge cases) is less important than validation throughput.

import { fastFormats } from 'ajv-formats';

// fastFormats includes a subset of fullFormats with optimized regex:
// date, time, date-time, iso-time, iso-date-time, uri, 
// uri-reference, email

The fullFormats object contains the complete set of format definitions provided by this package. Each definition includes a validator (often a RegExp or a function) and, where applicable, a comparison function for sorting or comparing values. Use this when you need strict adherence to standards like RFC 3339 for dates or RFC 6901 for JSON pointers.

import { fullFormats } from 'ajv-formats';

// fullFormats contains all supported formats including:
// date, time, date-time, iso-time, iso-date-time, duration, uri, 
// uri-reference, uri-template, url, email, hostname, ipv4, ipv6, 
// regex, uuid, json-pointer, json-pointer-uri-fragment, 
// relative-json-pointer, byte, int32, int64, float, double, 
// password, binary

The ajv-formats package provides a set of predefined format names that can be used in JSON Schema validation. These names are used to identify specific data types and patterns like dates, URIs, emails, and more.

// The following are valid FormatName values:
// "date" | "time" | "date-time" | "iso-time" | "iso-date-time" | "duration" | "uri" | "uri-reference" | "uri-template" | "url" | "email" | "hostname" | "ipv4" | "ipv6" | "regex" | "uuid" | "json-pointer" | "json-pointer-uri-fragment" | "relative-json-pointer" | "byte" | "int32" | "int64" | "float" | "double" | "password" | "binary"

The formatsPlugin exports a get method that allows you to manually retrieve a specific Format definition from the plugin's internal registry. This is useful if you need to access the underlying validation logic outside of the standard Ajv registration flow.

• format: FormatName: The name of the format to retrieve.
• mode?: FormatMode: The mode to search in ("fast" or "full"). Defaults to "full".

import formatsPlugin from "ajv-formats";

// Retrieve the 'email' format in 'full' mode
const emailFormat = formatsPlugin.get("email");

// Retrieve a format in 'fast' mode
const fastDate = formatsPlugin.get("date", "fast");