ajv-errors

ajv-errors is an official Ajv plugin that adds an errorMessage keyword to JSON Schema, letting schema authors define custom, human-readable validation error text directly inside the schema — replacing Ajv’s generic keyword-based errors (“should be integer”, “should have required property”) with messages tailored to the application’s domain and end users.

Messages can target a whole schema, specific keywords, or specific properties/items, support string interpolation from the data being validated via JSON-pointer templates, and can either replace or (optionally) supplement Ajv’s original error list — all generated at schema-compile time via Ajv’s code-generation API for zero runtime overhead beyond normal validation.

What You Get

• An errorMessage keyword usable as a single string (replaces all errors in that schema) or an object keyed by keyword/property name
• Per-keyword custom messages (e.g. distinct text for type, required, additionalProperties errors)
• Per-property and per-item message targeting via errorMessage.properties/errorMessage.items, regardless of where in the schema the error originated
• JSON-pointer template interpolation (${/path}) to embed the actual invalid value into the generated message
• singleError and keepErrors options controlling whether messages are merged into one error and whether original Ajv errors are preserved alongside custom ones

Common Use Cases

• Returning user-facing, translatable validation messages from an API instead of Ajv’s default keyword-oriented error text
• Building form-validation UIs that need one specific error message per field rather than Ajv’s raw error array
• Consolidating multiple validation failures on a single object into one summarized error string via singleError
• Embedding the actual invalid value into an error message (e.g. “must be >= 4, got 2”) using JSON-pointer interpolation

Under The Hood

Architecture - The entire plugin is a single src/index.ts (~394 lines) that registers one custom keyword (errorMessage) with Ajv via ajv.addKeyword, implemented using Ajv’s CodeKeywordDefinition/code-generation API (gen, _, str) rather than a runtime validation function — meaning the error-message logic is compiled directly into the generated validator function at ajv.compile() time. It walks it.errors/N.errors counters after child keyword validation runs (post: true) to find matching keyword/property errors, splices them out (unless keepErrors is set), and synthesizes new errorMessage-keyword error objects with the templated text, using Ajv’s own reportError helper. Tech Stack - Written entirely in TypeScript, with ajv itself as a peer dependency (v8.x — a breaking change from the v6-compatible v1 line) and internal imports reaching into Ajv’s compiled internals (ajv/dist/compile/codegen, ajv/dist/compile/validate, ajv/dist/compile/errors) rather than only its public API, reflecting how tightly this plugin is coupled to Ajv’s internal compiler. Built with tsc to dist/, tested with jest against a spec/ suite. Code Quality - The spec/ directory contains a Jest test suite (run via test-cov for coverage) exercising single-message, per-keyword, per-property, and templated-message scenarios; prettier/eslint checks and a build step are chained into the test script and enforced via a husky pre-commit hook, so quality gates run before every commit. API Design - The single errorMessage keyword with three shapes (string, keyword-map, property-map) keeps the schema-author-facing surface compact, and the ${/pointer} interpolation syntax reuses the already-familiar JSON-pointer/relative-pointer conventions from JSON Schema itself rather than inventing a new templating language — the main learning curve is understanding which original errors get matched and replaced versus left alone.