ajv-formats

ajv-formats plugs a full set of JSON Schema string format validators into Ajv, the widely used JSON Schema validator for JavaScript and TypeScript. Rather than writing custom regex or ad-hoc checks for values like dates, emails, and UUIDs, developers register this plugin once and get spec-compliant format keyword validation across their whole schema set.

The package ships both a full and a fast validation mode, plus companion comparison keywords (formatMinimum, formatMaximum, and their exclusive variants) for ordering constraints on formatted strings such as dates and times. It has no runtime dependency beyond Ajv itself, making it a lightweight drop-in for any project already validating JSON Schemas.

What You Get

• Over 20 predefined JSON Schema formats: date, time, date-time, duration, uri, uri-reference, uri-template, email, hostname, ipv4, ipv6, regex, uuid, json-pointer, and more
• A mode option (“full” or “fast”) to trade strict RFC compliance for faster, simplified regex checks in performance-sensitive paths
• Comparison keywords formatMinimum/formatMaximum/formatExclusiveMinimum/formatExclusiveMaximum for range constraints on ordered formats like dates and times
• A formats.get() accessor for reusing a single format validator function outside of an Ajv instance
• Zero required runtime dependencies beyond Ajv, keeping bundle size and supply-chain surface small

Common Use Cases

• Validating REST or GraphQL API request bodies where fields like email, date-time, or uuid must match a precise external format
• Enforcing OpenAPI 3.0 data-type formats (int32, int64, float, double, byte, binary, password) when validating schemas generated from an OpenAPI spec
• Adding date/time range checks (e.g. a startDate must be before an endDate) using the formatMinimum/formatMaximum keywords
• Selectively whitelisting only a handful of formats (e.g. just "date" and "time") to keep validation footprint minimal in constrained environments

Under The Hood

Architecture ajv-formats is a single default-export function (formatsPlugin in src/index.ts) that Ajv’s plugin convention calls with an Ajv instance and an options object; it looks up either the fullFormats or fastFormats table exported from src/formats.ts and registers each named format via ajv.addFormat(), optionally also wiring the comparison keywords defined in src/limit.ts. Tech Stack The codebase is a small TypeScript project (three source files, ~430 lines) built with tsc, tested with Jest against the shared JSON-Schema-Test-Suite fixtures, and linted with ESLint/Prettier via the @ajv-validator/config shared config; its only runtime dependency is a peer dependency on ajv itself. Code Quality Tests are thorough for the package’s scope: tests/index.spec.ts, tests/formatLimit.spec.ts, and a json-schema.spec.js runner exercise every format against the official JSON-Schema-Test-Suite submodule, and CI (npm test) chains prettier-check, build, eslint, and coverage before allowing a commit via a Husky pre-commit hook. Code is typed throughout with explicit interfaces (FormatsPlugin, FormatOptions) rather than any. API Design The public surface is intentionally minimal: a single function call (addFormats(ajv, options)) with a well-documented options object supporting an array shorthand or an object form, plus a static .get() accessor for reusing one validator function outside of Ajv. This keeps onboarding friction low but the format-name union type and mode-switching options require reading the README to discover, since types alone don’t convey the RFC-source-per-format nuance.