ata-validator 1.15.0 → 1.16.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.16.1 - 2026-09-12
+
+### Fixed
+
+- A custom format (`formats: { name: fn }`, or `addFormat` on the compat class) next to a shape the combined code generator declines, such as an `anyOf` sibling, threw `_uf_<name> is not defined` on the first invalid document instead of reporting the format error. The error-path code generator emitted the call to the format checker without binding it; it now takes the checkers as bound parameters like the other two entry points. Verdicts were never affected, only the error path, and only on that combination. Present since custom formats were added; caught by the 1.16.0 clean-install check. `tests/test_user_format_error_path.js` covers it.
+
+## 1.16.0 - 2026-09-12
+
+### Added
+
+- Custom keywords. `new Validator(schema, { keywords: { name: definition } })` registers keywords with a `validate(value, data, parentSchema)` function, a `compile(value, parentSchema)` factory, or a `macro(value, parentSchema)` that returns a schema applied in place. A definition can name the JSON Schema `type` it applies to. A schema that uses a registered keyword runs on the interpreted engine, so `anyOf`, `not`, `$ref` and the other applicators keep their meaning around the custom check; the compiled engines, the tier-0 plan and the native walker are all routed away from such schemas, and `bundleStandalone` refuses them instead of emitting a module that would ignore the keyword. Verdict paths (`isValidObject`, `isValidJSON`) agree with `validate()`. A keyword definition with none of the three forms throws, so a `code`-only definition is never accepted quietly.
+- `ata-validator/compat` covers the reference class's surface: `compileAsync`, `removeSchema` (by key, by object, by RegExp, or everything), `validateSchema` against the vendored meta-schemas, `addFormat` in its four forms, `addKeyword` in the `validate`, `compile` and `macro` forms plus the bare-name form, `addVocabulary`, `getKeyword`, `removeKeyword`, `errorsText`, `addMetaSchema`, `ajv.errors` and `ajv.opts`; and the constructor options `allErrors`, `useDefaults` (off by default, as in the reference), `coerceTypes`, `removeAdditional`, `verbose`, `validateFormats`, `validateSchema`, `formats`, `keywords` and `schemas`. `compile` throws `schema is invalid: ...` on a schema the meta-schema rejects, and caches by schema object. A schema with no `$schema` is read as draft-07, which is what `require('ajv')` does.
+- The shim reports errors in the reference's shape and order: keywords sorted the way the reference evaluates them rather than in declaration order, the failing branches before an `anyOf` or `oneOf`, each bad property name with its own errors and a `propertyNames` error, items before `contains` and an `if` error after a failed `then`/`else` under `allErrors`, draft-07 `dependencies` named as such, and with `allErrors` off the first failing keyword's whole group. `tests/test_ajv_parity.js` runs 32 scenarios of real consumer call shapes through both implementations and compares the results field by field; the reference is a devDependency and never ships.
+
+### Changed
+
+- `ata-validator/compat` refuses what it cannot honour instead of accepting it: `$data: true` throws at construction, a `code`-only keyword throws at `addKeyword`, and the reference's formats plugin throws with a note that its formats are built in.
+
 ## 1.13.1 - 2026-09-06
 
 ### Fixed

package/README.md

@@ -148,7 +148,7 @@ const v = new Validator(schema)
 const result = v.validate(data)
 ```
 
-The runtime API is unchanged from previous releases. AJV-shim users continue importing from `ata-validator/compat`.
+The runtime API is unchanged from previous releases. Code written against the default validator's class keeps working through `ata-validator/compat`, which covers `compile`, `addSchema`, `addFormat`, `addKeyword`, `errorsText` and the rest of that surface, and reports errors in the same shape and order. See [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
 
 ## Usage
 
@@ -471,6 +471,29 @@ auto result = ata::validate(schema, R"({"name": "Mert"})");
 // result.valid == true
 ```
 
+### Custom keywords
+
+Register keywords the schema vocabulary does not have with the `keywords` option. A definition is a `validate` function, a `compile` factory, or a `macro` that returns a schema, with an optional `type` that limits which values it sees.
+
+```javascript
+const v = new Validator(
+  { properties: { title: { type: 'string', maxWords: 5 } } },
+  {
+    keywords: {
+      maxWords: {
+        type: 'string',
+        compile: (n) => (s) => s.split(/\s+/).length <= n,
+      },
+    },
+  },
+)
+
+v.validate({ title: 'one two three four five six' })
+// { valid: false, errors: [{ keyword: 'maxWords', instancePath: '/title', ... }] }
+```
+
+A schema that uses a custom keyword runs on the interpreted engine, where `anyOf`, `not` and `$ref` keep their meaning around the custom check, and it cannot be compiled ahead of time, since a standalone module imports nothing and cannot carry the function. `bundleStandalone` refuses such schemas rather than emitting a module that would ignore the keyword. See [docs/custom-keywords.md](docs/custom-keywords.md).
+
 ## Framework integrations
 
 Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See [docs/integrations](docs/integrations/) for the full set.
@@ -478,7 +501,9 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 | Framework | Pattern | Recipe |
 |---|---|---|
 | Fastify | dedicated plugin | [`fastify-ata`](https://github.com/ata-core/fastify-ata) |
-| Vite (build-time compile) | dedicated plugin | [`ata-vite`](https://github.com/ata-core/ata-vite) |
+| Vite, Webpack, Rollup, Rolldown, esbuild, Rspack (build-time compile) | dedicated plugin | [`@ata-project/unplugin`](https://github.com/ata-core/unplugin-ata) |
+| Vite (build-time compile) | dedicated plugin | [`ata-vite`](https://github.com/ata-core/ata-vite), the Vite entry of the plugin above |
+| Next.js (build-time compile) | webpack entry of the plugin above | `@ata-project/unplugin/webpack` in `next.config.js` |
 | Hono | async middleware | [docs/integrations/hono.md](docs/integrations/hono.md) |
 | Elysia | direct handler check | [docs/integrations/elysia.md](docs/integrations/elysia.md) |
 | tRPC | Standard Schema V1 input | [docs/integrations/trpc.md](docs/integrations/trpc.md) |

package/compat.d.ts

@@ -1,23 +1,95 @@
-interface AjvError {
-  instancePath: string;
-  schemaPath: string;
-  keyword: string;
-  params: Record<string, unknown>;
-  message: string;
-}
+import type { JSONSchema } from './index';
+
+declare class Ata {
+  constructor(opts?: Ata.Options);
+  readonly opts: Ata.Options & { code: object };
+  /** Errors from the last `validate()` or `validateSchema()` call. */
+  errors: Ata.ErrorObject[] | null;
+
+  compile<T = unknown>(schema: object | boolean): Ata.ValidateFunction<T>;
+  compileAsync<T = unknown>(schema: object | boolean): Promise<Ata.ValidateFunction<T>>;
+  validate(schemaKeyRef: object | boolean | string, data: unknown): boolean;
+
+  addSchema(schema: object | object[], key?: string): this;
+  addMetaSchema(schema: object, key?: string): this;
+  getSchema<T = unknown>(keyRef: string): Ata.ValidateFunction<T> | undefined;
+  removeSchema(schemaKeyRef?: object | string | RegExp): this;
+  validateSchema(schema: object | boolean, throwOrLogError?: boolean): boolean;
+
+  addFormat(name: string, format: Ata.Format): this;
 
-interface ValidateFunction {
-  (data: unknown): boolean;
-  errors: AjvError[] | null;
-  schema: object;
+  addKeyword(definition: Ata.KeywordDefinition): this;
+  addKeyword(keyword: string, definition?: Omit<Ata.KeywordDefinition, 'keyword'>): this;
+  addVocabulary(definitions: Array<string | Ata.KeywordDefinition>): this;
+  getKeyword(keyword: string): Ata.KeywordDefinition | boolean;
+  removeKeyword(keyword: string): this;
+
+  errorsText(errors?: Ata.ErrorObject[] | null, options?: { separator?: string; dataVar?: string }): string;
 }
 
-declare class Ata {
-  constructor(opts?: Record<string, unknown>);
-  compile(schema: object): ValidateFunction;
-  validate(schema: object, data: unknown): boolean;
-  addSchema(schema: object, key?: string): this;
-  getSchema(key: string): ValidateFunction | undefined;
+declare namespace Ata {
+  interface ErrorObject {
+    instancePath: string;
+    schemaPath: string;
+    keyword: string;
+    params: Record<string, unknown>;
+    message: string;
+    /** Present when `verbose: true`. */
+    parentSchema?: unknown;
+    /** Present on errors produced under `propertyNames`. */
+    propertyName?: string;
+    [extra: string]: unknown;
+  }
+
+  interface ValidateFunction<T = unknown> {
+    (data: unknown): data is T;
+    errors: ErrorObject[] | null;
+    schema: object | boolean;
+  }
+
+  type Format =
+    | RegExp
+    | string
+    | ((data: string) => boolean)
+    | { type?: 'string' | 'number'; validate: RegExp | string | ((data: string) => boolean) };
+
+  interface KeywordDefinition {
+    keyword: string;
+    /** JSON Schema type name(s) the keyword applies to. Other types pass. */
+    type?: string | string[];
+    /** Called per value. May leave error objects on itself (`fn.errors`). */
+    validate?: (schema: unknown, data: unknown, parentSchema?: object) => boolean;
+    /** Called once per schema node; the returned function runs per value. */
+    compile?: (schema: unknown, parentSchema?: object) => (data: unknown) => boolean;
+    /** Returns a schema applied in place of the keyword. */
+    macro?: (schema: unknown, parentSchema?: object) => JSONSchema | boolean;
+    errors?: boolean;
+    [extra: string]: unknown;
+  }
+
+  interface Options {
+    allErrors?: boolean;
+    verbose?: boolean;
+    coerceTypes?: boolean | 'array';
+    useDefaults?: boolean | 'empty';
+    removeAdditional?: boolean | 'all' | 'failing';
+    validateFormats?: boolean;
+    validateSchema?: boolean | 'log';
+    formats?: Record<string, Format>;
+    keywords?: KeywordDefinition[];
+    schemas?: object[] | Record<string, object>;
+    strict?: boolean | 'log';
+    strictSchema?: boolean | 'log';
+    strictTypes?: boolean | 'log';
+    strictTuples?: boolean | 'log';
+    strictRequired?: boolean | 'log';
+    allowUnionTypes?: boolean;
+    logger?: { log(...args: unknown[]): void; warn(...args: unknown[]): void; error(...args: unknown[]): void } | false;
+    loadSchema?: (uri: string) => Promise<object>;
+    /** Refused: the constructor throws. */
+    $data?: boolean;
+    [extra: string]: unknown;
+  }
 }
 
 export = Ata;

package/compat.js

@@ -1,43 +1,394 @@
-const { Validator } = require("./index");
+'use strict';
+
+// Drop-in for the default validator's class. `const Ajv = require('ata-validator/compat')`
+// and the rest of the file stays as it was: `new Ajv(opts)`, `compile`,
+// `validate`, `addSchema`, `getSchema`, `removeSchema`, `addFormat`,
+// `addKeyword`, `errorsText`, `validateSchema`, `compileAsync`.
+//
+// The class reads schemas the way `require('ajv')` does: a schema that names
+// no `$schema` is draft-07. tests/test_ajv_parity.js runs a corpus of real
+// call shapes through both implementations and compares what comes back.
+//
+// What is not carried over, and refused rather than accepted quietly:
+//   - `$data` references;
+//   - keywords defined only through `code` (a code generator hook);
+//   - the reference formats plugin, whose formats are built in here.
+// Strict-mode schema checks (`strict`, `strictTypes`, ...) are accepted and
+// ignored: an unknown keyword is an annotation, as the specification says.
+
+const { Validator } = require('./index');
+const { METASCHEMAS } = require('./lib/metaschemas');
+const { createShaper } = require('./lib/compat-errors');
+
+const DRAFT7 = 'http://json-schema.org/draft-07/schema#';
+const DRAFT2020 = 'https://json-schema.org/draft/2020-12/schema';
+
+function isDraft7Id(id) {
+  return id === DRAFT7 || id === 'http://json-schema.org/draft-07/schema';
+}
+
+function formatToFunction(name, format) {
+  if (typeof format === 'function') return format;
+  if (format instanceof RegExp) return (s) => format.test(s);
+  if (typeof format === 'string') {
+    const re = new RegExp(format, 'u');
+    return (s) => re.test(s);
+  }
+  if (format === true) return () => true;
+  if (format && typeof format === 'object') {
+    if (typeof format.validate === 'function') return format.validate;
+    if (format.validate instanceof RegExp) return (s) => format.validate.test(s);
+    if (typeof format.validate === 'string') {
+      const re = new RegExp(format.validate, 'u');
+      return (s) => re.test(s);
+    }
+    if (format.async) throw new Error(`format "${name}": async formats are not supported`);
+  }
+  throw new Error(`format "${name}": unsupported format definition`);
+}
+
 
 class Ata {
   constructor(opts = {}) {
-    this._opts = opts;
-    this._schemas = new Map();
+    if (opts.$data) {
+      throw new Error('ata compat: $data references are not supported');
+    }
+    this.opts = { ...opts };
+    // The formats plugin of the reference assigns into `opts.code.formats`
+    // before registering anything; the formats it carries are built in here,
+    // so say so at that exact point instead of failing further down.
+    const code = { ...(opts.code || {}) };
+    Object.defineProperty(code, 'formats', {
+      get() { return undefined; },
+      set() {
+        throw new Error('ata compat: the formats plugin is not needed, formats such as email, uri, date-time and uuid are built in; remove addFormats()');
+      },
+    });
+    this.opts.code = code;
+
+    this.errors = null;
+    this._schemas = new Map();      // key or $id -> schema object
+    this._byKey = new Map();        // key -> $id (when both exist)
+    this._formats = Object.create(null);
+    this._keywords = Object.create(null);
+    this._compiled = new WeakMap(); // schema object -> validate function
+    this._registry = null;          // Validator `schemas` option, rebuilt on change
+    this._registryEpoch = 0;
+
+    if (opts.formats) {
+      for (const name of Object.keys(opts.formats)) this.addFormat(name, opts.formats[name]);
+    }
+    if (Array.isArray(opts.keywords)) {
+      for (const def of opts.keywords) this.addKeyword(def);
+    }
+    if (opts.schemas) {
+      if (Array.isArray(opts.schemas)) this.addSchema(opts.schemas);
+      else for (const key of Object.keys(opts.schemas)) this.addSchema(opts.schemas[key], key);
+    }
+  }
+
+  // ----- options -------------------------------------------------------
+
+  _validatorOptions() {
+    const o = this.opts;
+    const out = {
+      useDefaults: !!o.useDefaults,
+      coerceTypes: !!o.coerceTypes,
+      removeAdditional: !!o.removeAdditional,
+      verbose: !!o.verbose,
+    };
+    if (o.validateFormats === false) out.assertFormat = false;
+    const formatNames = Object.keys(this._formats);
+    if (formatNames.length > 0) out.formats = { ...this._formats };
+    const keywordNames = Object.keys(this._keywords);
+    if (keywordNames.length > 0) {
+      const kws = {};
+      for (const name of keywordNames) if (this._keywords[name] !== true) kws[name] = this._keywords[name];
+      if (Object.keys(kws).length > 0) out.keywords = kws;
+    }
+    const registry = this._registrySnapshot();
+    if (registry) out.schemas = registry;
+    return out;
   }
 
+  _registrySnapshot() {
+    if (this._schemas.size === 0) return null;
+    if (this._registry === null) {
+      const map = {};
+      for (const [key, schema] of this._schemas) map[key] = this._withDialect(schema);
+      this._registry = map;
+    }
+    return this._registry;
+  }
+
+  _touchRegistry() {
+    this._registry = null;
+    this._registryEpoch++;
+  }
+
+  // A schema with no `$schema` is read as draft-07, which is what the
+  // reference class does. The copy is shallow: only the root changes.
+  _withDialect(schema) {
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) return schema;
+    if (typeof schema.$schema === 'string') return schema;
+    return { $schema: DRAFT7, ...schema };
+  }
+
+  // ----- compile / validate --------------------------------------------
+
   compile(schema) {
-    const v = new Validator(schema);
+    if (typeof schema === 'object' && schema !== null) {
+      const hit = this._compiled.get(schema);
+      if (hit && hit._epoch === this._registryEpoch) return hit;
+    }
+    if (this.opts.validateSchema !== false && typeof schema === 'object' && schema !== null) {
+      if (!this.validateSchema(schema)) {
+        const message = 'schema is invalid: ' + this.errorsText();
+        if (this.opts.validateSchema === 'log') {
+          const logger = this.opts.logger;
+          if (logger && typeof logger.error === 'function') logger.error(message);
+        } else {
+          throw new Error(message);
+        }
+      }
+    }
+    const rootDoc = this._withDialect(schema);
+    const options = this._validatorOptions();
+    const allErrors = !!this.opts.allErrors;
+    let shaper = null;
+    if (typeof rootDoc === 'object' && rootDoc !== null) {
+      // The root is registered under a private id so the error shaper can
+      // re-validate any subschema of it by pointer, with every `$ref` in it
+      // still resolving.
+      const rootId = 'ata-compat:root';
+      options.schemas = { ...(options.schemas || {}), [rootId]: rootDoc };
+      shaper = createShaper({
+        Validator, rootId, rootDoc, options, allErrors,
+        macroKeywords: Object.keys(this._keywords).filter((k) => this._keywords[k] !== true && this._keywords[k].macro),
+      });
+    }
+    const v = new Validator(rootDoc, options);
     const validate = (data) => {
       const result = v.validate(data);
-      validate.errors = result.valid ? null : result.errors;
-      return result.valid;
+      if (result.valid) {
+        validate.errors = null;
+        return true;
+      }
+      const errors = shaper === null ? result.errors : shaper(result.errors, data);
+      validate.errors = shaper === null && !allErrors ? errors.slice(0, 1) : errors;
+      return false;
     };
     validate.errors = null;
     validate.schema = schema;
+    validate._epoch = this._registryEpoch;
+    if (typeof schema === 'object' && schema !== null) this._compiled.set(schema, validate);
     return validate;
   }
 
-  validate(schema, data) {
-    const validate = this.compile(schema);
-    return validate(data);
+  compileAsync(schema) {
+    return new Promise((resolve, reject) => {
+      try { resolve(this.compile(schema)); } catch (e) { reject(e); }
+    });
   }
 
+  validate(schemaKeyRef, data) {
+    let validate;
+    if (typeof schemaKeyRef === 'string') {
+      validate = this.getSchema(schemaKeyRef);
+      if (!validate) throw new Error(`no schema with key or ref "${schemaKeyRef}"`);
+    } else {
+      validate = this.compile(schemaKeyRef);
+    }
+    const valid = validate(data);
+    this.errors = validate.errors;
+    return valid;
+  }
+
+  // ----- schema registry -----------------------------------------------
+
   addSchema(schema, key) {
-    if (key) {
-      this._schemas.set(key, schema);
-    } else if (schema.$id) {
-      this._schemas.set(schema.$id, schema);
+    if (Array.isArray(schema)) {
+      for (const s of schema) this.addSchema(s);
+      return this;
+    }
+    const id = schema && typeof schema === 'object' && typeof schema.$id === 'string' ? schema.$id : undefined;
+    const k = key !== undefined ? String(key) : id;
+    if (k === undefined) throw new Error('schema with key or id "undefined" cannot be added: no key and no $id');
+    if (this._schemas.has(k) && this._schemas.get(k) !== schema) {
+      throw new Error(`schema with key or id "${k}" already exists`);
     }
+    this._schemas.set(k, schema);
+    if (id !== undefined && id !== k) {
+      this._schemas.set(id, schema);
+      this._byKey.set(k, id);
+    }
+    this._touchRegistry();
     return this;
   }
 
-  getSchema(key) {
-    const schema = this._schemas.get(key);
-    if (schema) return this.compile(schema);
+  addMetaSchema(schema, key) {
+    return this.addSchema(schema, key);
+  }
+
+  getSchema(keyRef) {
+    const schema = this._schemas.get(keyRef);
+    if (schema !== undefined) return this.compile(schema);
+    // A fragment into a registered document: compile a reference to it.
+    const hash = keyRef.indexOf('#');
+    if (hash > 0 && this._schemas.has(keyRef.slice(0, hash))) {
+      return this.compile({ $ref: keyRef });
+    }
     return undefined;
   }
+
+  removeSchema(schemaKeyRef) {
+    if (schemaKeyRef === undefined) {
+      this._schemas.clear();
+      this._byKey.clear();
+      this._compiled = new WeakMap();
+      this._touchRegistry();
+      return this;
+    }
+    if (schemaKeyRef instanceof RegExp) {
+      for (const key of Array.from(this._schemas.keys())) {
+        if (schemaKeyRef.test(key)) this._removeKey(key);
+      }
+      return this;
+    }
+    if (typeof schemaKeyRef === 'object' && schemaKeyRef !== null) {
+      for (const [key, schema] of Array.from(this._schemas)) {
+        if (schema === schemaKeyRef) this._removeKey(key);
+      }
+      this._compiled.delete(schemaKeyRef);
+      return this;
+    }
+    this._removeKey(String(schemaKeyRef));
+    return this;
+  }
+
+  _removeKey(key) {
+    const schema = this._schemas.get(key);
+    if (schema === undefined) return;
+    this._schemas.delete(key);
+    const alias = this._byKey.get(key);
+    if (alias !== undefined) {
+      this._schemas.delete(alias);
+      this._byKey.delete(key);
+    }
+    for (const [k, id] of Array.from(this._byKey)) {
+      if (id === key) { this._schemas.delete(k); this._byKey.delete(k); }
+    }
+    if (typeof schema === 'object' && schema !== null) this._compiled.delete(schema);
+    this._touchRegistry();
+  }
+
+  validateSchema(schema, throwOrLogError) {
+    if (typeof schema === 'boolean') { this.errors = null; return true; }
+    if (typeof schema !== 'object' || schema === null) {
+      this.errors = [{ keyword: 'type', instancePath: '', schemaPath: '#/type', params: { type: 'object' }, message: 'must be object,boolean' }];
+      return false;
+    }
+    const declared = typeof schema.$schema === 'string' ? schema.$schema : DRAFT7;
+    const metaId = METASCHEMAS.has(declared) ? declared : isDraft7Id(declared) ? DRAFT7 : DRAFT2020;
+    const meta = metaValidator(metaId);
+    const result = meta.validate(schema);
+    if (result.valid) { this.errors = null; return true; }
+    this.errors = result.errors;
+    if (throwOrLogError) {
+      const message = 'schema is invalid: ' + this.errorsText();
+      if (this.opts.validateSchema === 'log') {
+        const logger = this.opts.logger;
+        if (logger && typeof logger.error === 'function') logger.error(message);
+      } else {
+        throw new Error(message);
+      }
+    }
+    return false;
+  }
+
+  // ----- formats -------------------------------------------------------
+
+  addFormat(name, format) {
+    this._formats[name] = formatToFunction(name, format);
+    this._compiled = new WeakMap();
+    return this;
+  }
+
+  // ----- keywords ------------------------------------------------------
+
+  addKeyword(kwdOrDef, def) {
+    let keyword;
+    let definition;
+    if (typeof kwdOrDef === 'string') {
+      keyword = kwdOrDef;
+      definition = def;
+    } else if (kwdOrDef && typeof kwdOrDef === 'object') {
+      keyword = kwdOrDef.keyword;
+      definition = kwdOrDef;
+    }
+    if (typeof keyword !== 'string' || keyword === '') {
+      throw new Error('addKeyword: keyword must be a non-empty string');
+    }
+    if (this._keywords[keyword] !== undefined) {
+      throw new Error(`keyword "${keyword}" is already defined`);
+    }
+    if (!definition || (typeof definition === 'object' && !definition.validate && !definition.compile && !definition.macro && !definition.code)) {
+      // A bare name: the keyword is known and checks nothing.
+      this._keywords[keyword] = true;
+      return this;
+    }
+    if (typeof definition.code === 'function' && !definition.validate && !definition.compile && !definition.macro) {
+      throw new Error(`keyword "${keyword}": code-generating keywords are not supported; define it with validate, compile or macro`);
+    }
+    const mapped = {};
+    if (definition.type !== undefined) mapped.type = definition.type;
+    if (typeof definition.validate === 'function') mapped.validate = definition.validate;
+    if (typeof definition.compile === 'function') mapped.compile = definition.compile;
+    if (typeof definition.macro === 'function') mapped.macro = definition.macro;
+    if (mapped.validate && mapped.compile) delete mapped.validate;
+    this._keywords[keyword] = mapped;
+    this._keywordDefs = this._keywordDefs || Object.create(null);
+    this._keywordDefs[keyword] = definition;
+    this._compiled = new WeakMap();
+    return this;
+  }
+
+  addVocabulary(definitions) {
+    for (const def of definitions) this.addKeyword(def);
+    return this;
+  }
+
+  getKeyword(keyword) {
+    const def = this._keywords[keyword];
+    if (def === undefined) return false;
+    return def === true ? true : (this._keywordDefs && this._keywordDefs[keyword]) || def;
+  }
+
+  removeKeyword(keyword) {
+    delete this._keywords[keyword];
+    if (this._keywordDefs) delete this._keywordDefs[keyword];
+    this._compiled = new WeakMap();
+    return this;
+  }
+
+  // ----- errors --------------------------------------------------------
+
+  errorsText(errors = this.errors, { separator = ', ', dataVar = 'data' } = {}) {
+    if (!errors || errors.length === 0) return 'No errors';
+    return errors.map((e) => `${dataVar}${e.instancePath} ${e.message}`).reduce((text, msg) => text + separator + msg);
+  }
+}
+
+const _metaValidators = new Map();
+function metaValidator(id) {
+  let v = _metaValidators.get(id);
+  if (!v) {
+    v = new Validator({ $ref: id }, { useDefaults: false });
+    _metaValidators.set(id, v);
+  }
+  return v;
 }
 
 module.exports = Ata;
 module.exports.default = Ata;
+module.exports.Ata = Ata;

package/index.d.ts

@@ -314,6 +314,26 @@ export type ValidateAndParseResult<T = unknown> =
   | { valid: true;  value: T;       errors: ValidationError[] }
   | { valid: false; value: unknown; errors: ValidationError[] };
 
+export type KeywordValidate = (schemaValue: unknown, data: unknown, parentSchema: object) => boolean;
+
+export interface KeywordDefinition {
+  /** JSON Schema type name(s) the keyword applies to. Other types pass. */
+  type?: string | string[];
+  /**
+   * Called per value with the keyword's value in the schema, the data, and
+   * the schema object that carries the keyword. May leave error objects on
+   * itself (`fn.errors`) to replace the default error.
+   */
+  validate?: KeywordValidate;
+  /** Called once per schema node; the returned function runs per value. */
+  compile?: (schemaValue: unknown, parentSchema: object) => (data: unknown) => boolean;
+  /**
+   * Returns a schema that is applied in place. Its errors carry the keyword's
+   * path, and the keyword reports an error of its own when it fails.
+   */
+  macro?: (schemaValue: unknown, parentSchema: object) => JSONSchema | boolean;
+}
+
 export interface ValidatorOptions {
   coerceTypes?: boolean;
   removeAdditional?: boolean;
@@ -336,6 +356,12 @@ export interface ValidatorOptions {
    * the schema. Values are functions that return true when the input is valid.
    */
   formats?: Record<string, FormatChecker>;
+  /**
+   * Custom keywords, keyed by name. A schema that uses one runs on the
+   * interpreted engine and cannot be compiled ahead of time. See
+   * docs/custom-keywords.md.
+   */
+  keywords?: Record<string, KeywordDefinition | KeywordValidate>;
   /**
    * When true, validation errors include `parentSchema` (the schema object
    * that produced the error). Matches ajv's `verbose: true`.