ata-validator 1.51.0 → 1.53.0

package/README.md

@@ -138,18 +138,19 @@ errors (7.6M with `richErrors: false`).
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 1.4 KB | 52.7 KB | 38.4x smaller |
-| Bundle (gzipped) | complex | 3.0 KB | 52.7 KB | 17.5x smaller |
-| Bundle (gzipped) | nested | 4.5 KB | 52.7 KB | 11.6x smaller |
+| Bundle (gzipped) | simple | 1.3 KB | 52.7 KB | 39.0x smaller |
+| Bundle (gzipped) | complex | 3.0 KB | 52.7 KB | 17.7x smaller |
+| Bundle (gzipped) | nested | 4.5 KB | 52.7 KB | 11.8x smaller |
 | Cold start | simple | 20 ms | 37 ms | 1.9x faster |
-| Throughput (1M ops) | simple | 289 Mops/s | 96 Mops/s | 3.0x faster |
-| Compile time | simple | 18 µs | 1.56 ms | 85x faster |
+| Throughput (1M ops) | simple | 315 Mops/s | 99 Mops/s | 3.2x faster |
+| Compile time | simple | 24 µs | 1.57 ms | 65x faster |
 
 The runtime column is the default validator most frameworks ship. Reproduce on your machine
-with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-10-06,
-on ata-validator 1.46.0. Across four runs throughput moved between 288 and 329 Mops/s against
-96 to 116, cold start between 19 and 20 ms against 37 to 39, and the compile ratio between 77x
-and 85x. The throughput row times a single one-million-call
+with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-10-11,
+on ata-validator 1.51.0. Across five runs throughput moved between 263 and 325 Mops/s against
+97 to 110, cold start between 20 and 22 ms against 37 to 40, and the compile ratio between 61x
+and 65x. The compile row is the time to write a module, a build-time cost; it was 18 µs on
+1.46.0, and modules have carried the one-pass error function since 1.47.0. The throughput row times a single one-million-call
 loop of a few milliseconds, so it moves the most from run to run; treat the last three rows as
 an order of magnitude rather than a constant.
 
@@ -279,13 +280,13 @@ is the most common way to get a misleading number out of this library.
 
 | | compiled with `ata build` | runtime `new Validator(schema)` |
 |---|---|---|
-| In a bundle, gzipped | **2.1 KB** | 126.1 KB |
+| In a bundle, gzipped | **2.1 KB** | 123.9 KB |
 | Time to a served request | **3.5 ms** | 7.6 ms |
 | Schema known when | build time | any time |
 
 The bundle row is the ten-field user schema in
 `tests/fixtures/error-dx/user.schema.json`, every export of the compiled module against
-`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.48.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.51.0.
 The startup row is a Hono route on Bun 1.4, the median of three rounds of best-of-seven, from
 `benchmark/bundle`, against 3.5 ms for the same app doing no validation at all, so the
 compiled path costs nothing measurable to start. The runtime figure is what it is because
@@ -293,7 +294,7 @@ a schema that arrives at run time can use any keyword, so the whole engine has t
 there. The compiled module imports nothing and contains only the checks your schema asks
 for.
 
-**On a server, use whichever fits your schemas.** 113 KB of JavaScript on a Node or Bun
+**On a server, use whichever fits your schemas.** 124 KB of JavaScript on a Node or Bun
 process is not a cost anyone notices, and the runtime API is the simpler thing to reach
 for. Speed is the same either way once warm.
 
@@ -535,7 +536,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 113.3 KB for the runtime bundled for the browser (ata 1.45.0).
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 123.9 KB for the runtime bundled for the browser (ata 1.51.0).
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -581,20 +582,25 @@ error collector out of the modules: each one carries its verdict and its schema,
 its errors from one `ata-errors.mjs` the build writes beside them. The build does this only
 where it makes the output smaller, so a single small schema keeps its self-contained module.
 The errors are the ones `new Validator(schema, { richErrors: false })` reports, in the same
-order. Seven SchemaStore schemas imported into one app, minified with esbuild, go from 148.9 KB
-to 63.3 KB gzipped, and from 35.8 ms to 13.8 ms to import with code generation blocked. A
+order. Forty SchemaStore schemas imported into one app, minified with esbuild, go from 513.8 KB
+to 213.3 KB gzipped, and from 60.4 ms to 28.4 ms to import with code generation blocked. A
 rejected document costs more this way, since its errors come from an interpreted walk:
 `--errors inline` keeps every module self-contained. `--mode schema` writes each module as
 its schema and takes the verdict from the runtime too: forty SchemaStore schemas in one app
-come to 101.6 KB gzipped against 212.6 KB as compact modules, and load and check each once in
-23.0 ms against 35.5, while a check once warm costs about five times what generated code costs.
+come to 102.4 KB gzipped against 213.3 KB as compact modules, and load and check each once in
+23.9 ms against 34.5, while a check once warm costs about five times what generated code costs.
+Schemas that reference each other by `$id` are built against each other, and in schema mode
+they are written once to a shared registry that keeps only the definitions the modules reach;
+`--base-uri <uri>` names files that declare no `$id`. Eight Kubernetes kinds, whose schemas
+share one 1.1 MB definitions file, come to 32.6 KB gzipped as schema modules against 68.6 KB
+self-contained, on ata 1.51.0.
 
 Bundle sizes for the 10-field user schema in `tests/fixtures/error-dx/user.schema.json`,
-minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.45.0:
+minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.51.0:
 
 | What the app imports | Size | Notes |
 |---|---|---|
-| `Validator` from `ata-validator` | 113.3 KB | The compiler ships with it, because a runtime schema can use any keyword |
+| `Validator` from `ata-validator` | 123.9 KB | The compiler ships with it, because a runtime schema can use any keyword |
 | `isValid` from the compiled module | **1.3 KB** | Nothing else is reachable, so the error collector is dropped |
 | `validate` from the compiled module | **1.9 KB** | Adds the detailed error collector |
 
@@ -632,7 +638,7 @@ through a `setFormats()` export the module carries. `docs/API.md` has the
 details.
 
 **Fastify startup, 10 route schemas, from a cold process to the first validated request:
-ajv 19.7 ms, ata 2.75 ms, no build step required.** ata registers in 0.25 ms of that and
+ajv 19.0 ms, ata 2.81 ms, no build step required.** ata registers in 0.20 ms of that and
 compiles on the first request, so counting only registration would overstate the gap.
 Reproduce with `node benchmark/bench_fastify_boot.mjs`.
 

package/compat.js

@@ -22,11 +22,26 @@ const { resolvePointer } = require('./lib/pointer.js');
 
 const { Validator } = require('./index');
 const { METASCHEMAS } = require('./lib/metaschemas');
+const { normalizeExclusiveBounds } = require('./lib/draft7');
 const { createShaper, asReferenceKeyword } = require('./lib/compat-errors');
 
 const DRAFT7 = 'http://json-schema.org/draft-07/schema#';
 const DRAFT2020 = 'https://json-schema.org/draft/2020-12/schema';
 
+// draft-04, which OpenAPI 3.0 builds on, is read as draft-07, the nearest
+// dialect ata implements: its boolean exclusiveMinimum and exclusiveMaximum
+// are normalized to the numeric form, and its `id` names the schema as `$id`
+// does. The reference ships a separate class for it (ajv-draft-04).
+const DRAFT4_IDS = new Set(['http://json-schema.org/draft-04/schema#', 'http://json-schema.org/draft-04/schema', 'https://json-schema.org/draft-04/schema#', 'https://json-schema.org/draft-04/schema']);
+function isDraft4(schema) {
+  return schema !== null && typeof schema === 'object' && typeof schema.$schema === 'string' && DRAFT4_IDS.has(schema.$schema);
+}
+function draft4AsDraft7(schema) {
+  const out = { ...schema, $schema: DRAFT7 };
+  if (typeof schema.id === 'string' && schema.$id === undefined) { out.$id = schema.id; delete out.id; }
+  return out;
+}
+
 function isDraft7Id(id) {
   return id === DRAFT7 || id === 'http://json-schema.org/draft-07/schema';
 }
@@ -58,17 +73,12 @@ class Ata {
       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;
+    // The formats plugin of the reference assigns into `opts.code.formats` and
+    // then registers each of its formats through addFormat, which is what it
+    // does here too. It is not needed (the formats are built in), but a
+    // library that calls it inside its own setup, as express-openapi-validator
+    // does, could not take this class at all while the call was refused.
+    this.opts.code = { ...(opts.code || {}) };
 
     this.errors = null;
     this._schemas = new Map();      // key or $id -> schema object
@@ -97,9 +107,13 @@ class Ata {
     const o = this.opts;
     const out = {
       useDefaults: !!o.useDefaults,
-      coerceTypes: !!o.coerceTypes,
+      coerceTypes: o.coerceTypes === 'array' ? 'array' : !!o.coerceTypes,
       removeAdditional: !!o.removeAdditional,
       verbose: !!o.verbose,
+      // The errors are reshaped into the reference's own; the fields only
+      // rich errors carry (code, received, suggestion, docUrl) are dropped on
+      // the way, so they are not built at all.
+      richErrors: false,
     };
     // `strict` and `strictSchema`: the unknown-keyword and dangling-local-$ref
     // checks are enforced; `strictTypes`, `strictTuples` and `strictRequired`
@@ -112,11 +126,9 @@ class Ata {
     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 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;
@@ -126,23 +138,111 @@ class Ata {
     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);
+      for (const [key, schema] of this._schemas) map[fragmentKey(key)] = this._fragmentRefs(this._withDialect(schema));
       this._registry = map;
     }
     return this._registry;
   }
 
+  // A schema registered under a key that is only a fragment
+  // (`addSchema(s, '#/components/schemas/Pet')`, as OpenAPI tools do) is
+  // found by a `$ref` of that exact string that does not resolve in its own
+  // document: the reference looks it up among the registered keys then. ata
+  // resolves a fragment in the document alone, so such a `$ref` is pointed at
+  // the key's entry in the registry (see fragmentKey).
+  _fragmentRefs(schema) {
+    if (schema === null || typeof schema !== 'object') return schema;
+    let keys = this._fragmentKeys;
+    if (keys === undefined || this._fragmentStale) {
+      // The copies stand while the fragment-only keys are the same ones.
+      const now = new Set();
+      for (const key of this._schemas.keys()) if (key.startsWith('#')) now.add(key);
+      this._fragmentStale = false;
+      if (keys === undefined || keys.size !== now.size || [...now].some((k) => !keys.has(k))) {
+        // Each key's pointer, split and decoded once.
+        keys = this._fragmentKeys = new Map();
+        for (const key of now) {
+          let segs = null;
+          if (key.startsWith('#/')) {
+            try { segs = key.slice(2).split('/').map((raw) => decodeURIComponent(raw.replace(/~1/g, '/').replace(/~0/g, '~'))); } catch { segs = null; }
+          }
+          keys.set(key, segs);
+        }
+        this._fragmentCopies = new WeakMap();
+      }
+    }
+    if (keys.size === 0) return schema;
+    const hit = this._fragmentCopies.get(schema);
+    if (hit !== undefined) return hit;
+    if ((features(schema) & F_REF) === 0) { this._fragmentCopies.set(schema, schema); return schema; }
+    const resolves = (key, segs) => {
+      if (key === '#') return true;
+      if (segs === null) return !key.startsWith('#/');
+      let node = schema;
+      for (let i = 0; i < segs.length; i++) {
+        if (node === null || typeof node !== 'object' || !Object.prototype.hasOwnProperty.call(node, segs[i])) return false;
+        node = node[segs[i]];
+      }
+      return true;
+    };
+    // Only a key that does not resolve in this document can need pointing
+    // elsewhere. A document that holds every registered fragment itself, as
+    // an OpenAPI tool's schema carrying the whole `components` does, is left
+    // as it is without a walk.
+    const pointed = new Set();
+    for (const [key, segs] of keys) if (!resolves(key, segs)) pointed.add(key);
+    if (pointed.size === 0) { this._fragmentCopies.set(schema, schema); return schema; }
+    let changed = false;
+    const copy = (n, data) => {
+      if (n === null || typeof n !== 'object') return n;
+      if (Array.isArray(n)) return n.map((x) => copy(x, data));
+      const out = {};
+      for (const k of Object.keys(n)) {
+        let v;
+        if (!data && k === '$ref' && typeof n[k] === 'string' && pointed.has(n[k])) { v = fragmentKey(n[k]); changed = true; }
+        else v = copy(n[k], !data && (k === 'const' || k === 'enum' || k === 'default' || k === 'examples' || k === 'example'));
+        if (k === '__proto__') Object.defineProperty(out, k, { value: v, writable: true, enumerable: true, configurable: true });
+        else out[k] = v;
+      }
+      return out;
+    };
+    const out = copy(schema, false);
+    const result = changed ? out : schema;
+    this._fragmentCopies.set(schema, result);
+    return result;
+  }
+
   _touchRegistry() {
+    this._fragmentStale = true;
     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.
+  // reference class does, or as `defaultMeta` when that names a dialect: the
+  // reference's 2020-12 class reads one as 2020-12, which is how an OpenAPI
+  // 3.1 document's schemas are meant. The copy is shallow: only the root
+  // changes.
+  // The copy is kept per schema object, so a schema compiled again or
+  // registered again is the same object to everything that remembers work
+  // per object below (the scan, normalization, the fragment copies).
   _withDialect(schema) {
     if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) return schema;
+    if (this._dialectCopies === undefined) this._dialectCopies = new WeakMap();
+    let out = this._dialectCopies.get(schema);
+    if (out === undefined) {
+      out = this._withDialectCopy(schema);
+      this._dialectCopies.set(schema, out);
+    }
+    return out;
+  }
+
+  _withDialectCopy(schema) {
+    if (isDraft4(schema)) return draft4AsDraft7(schema);
     if (typeof schema.$schema === 'string') return schema;
-    return { $schema: DRAFT7, ...schema };
+    const meta = typeof this.opts.defaultMeta === 'string' ? this.opts.defaultMeta : DRAFT7;
+    if (DRAFT4_IDS.has(meta)) return draft4AsDraft7({ $schema: meta, ...schema });
+    return { $schema: meta, ...schema };
   }
 
   // ----- compile / validate --------------------------------------------
@@ -163,9 +263,20 @@ class Ata {
         }
       }
     }
-    const rootDoc = this._withDialect(schema);
+    if (this._codeOnly && typeof schema === 'object' && schema !== null) {
+      const { schemaUsesKeywords } = require('./lib/keywords');
+      for (const name of Object.keys(this._codeOnly)) {
+        if (schemaUsesKeywords(schema, { [name]: this._codeOnly[name] }) || [...this._schemas.values()].some((s) => schemaUsesKeywords(s, { [name]: this._codeOnly[name] }))) {
+          throw new Error(`keyword "${name}": code-generating keywords are not supported; define it with validate, compile or macro`);
+        }
+      }
+    }
+    const rootDoc = this._fragmentRefs(this._withDialect(schema));
     const options = this._validatorOptions();
     const allErrors = !!this.opts.allErrors;
+    // The reference's `discriminator` option, for a schema that has one.
+    const discriminated = this.opts.discriminator === true &&
+      ((features(rootDoc) & F_DISCR) !== 0 || Object.values(options.schemas || {}).some((d) => features(d) & F_DISCR));
     let shaper = null;
     if (typeof rootDoc === 'object' && rootDoc !== null) {
       // The root is registered under a private id so the error shaper can
@@ -174,18 +285,47 @@ class Ata {
       const rootId = 'ata-compat:root';
       options.schemas = { ...(options.schemas || {}), [rootId]: rootDoc };
       shaper = createShaper({
-        Validator, rootId, rootDoc, options, allErrors,
+        Validator, rootId, rootDoc, options, allErrors, schemas: options.schemas, discriminator: discriminated,
         macroKeywords: Object.keys(this._keywords).filter((k) => this._keywords[k] !== true && this._keywords[k].macro),
       });
     }
+    // coerceTypes reaching a value behind allOf, anyOf, oneOf, $ref and the
+    // rest, where ata's coercion pass, which runs before validation and
+    // follows `properties` and `items`, does not: the interpreted engine then
+    // coerces where each `type` is checked, as the reference does.
+    if (options.coerceTypes && (features(rootDoc) & F_BEYOND) !== 0) {
+      options._coerceInWalk = this.opts.coerceTypes === 'array' ? 'array' : true;
+      options.coerceTypes = false;
+      options.engine = 'interpreter';
+    }
+    // The reference's `discriminator` option: the interpreted engine reads the
+    // keyword (see discriminate in lib/interpreter-core.js).
+    // A format registered for numbers, for a schema that names a format.
+    if (this._numFormats && Object.keys(this._numFormats).length > 0 &&
+        ((features(rootDoc) & F_FORMAT) !== 0 || Object.values(options.schemas || {}).some((d) => features(d) & F_FORMAT))) {
+      options._numberFormats = { ...this._numFormats };
+      options.engine = 'interpreter';
+    }
+    if (discriminated) {
+      options._discriminator = true;
+      options.engine = 'interpreter';
+    }
     const v = new Validator(rootDoc, options);
+    const defaults = this.opts.useDefaults ? referencedDefaults(rootDoc, options.schemas) : null;
+    // With keywords that read their data's context, the shaper is given the
+    // errors as the validator made them: those carry each anyOf and oneOf
+    // branch's errors (see keepBranches in lib/interpreter-core.js), which the
+    // copies handed out do not.
+    const ctxKeywords = options.keywords !== undefined && Object.values(options.keywords).some((k) => k && k.dataContext === true);
     const validate = (data) => {
+      if (defaults !== null) defaults(data);
       const result = v.validate(data);
       if (result.valid) {
         validate.errors = null;
         return true;
       }
-      let errors = shaper === null ? result.errors.map(asReferenceKeyword) : shaper(result.errors, data);
+      const raw = ctxKeywords && shaper !== null && typeof result._ataRaw === 'function' ? result._ataRaw() : result.errors;
+      let errors = shaper === null ? result.errors.map(asReferenceKeyword) : shaper(raw, data);
       // Errors the shaper synthesises, the `if` wrapper among them, are built
       // from the group rather than carried up from the validator, so verbose
       // mode has to fill in the value they point at here or they would be the
@@ -195,7 +335,7 @@ class Ata {
           ? { ...e, data: resolvePointer(data, e.instancePath || '', undefined) }
           : e));
       }
-      validate.errors = shaper === null && !allErrors ? errors.slice(0, 1) : errors;
+      validate.errors = inReferenceOrder(shaper === null && !allErrors ? errors.slice(0, 1) : errors);
       return false;
     };
     validate.errors = null;
@@ -231,7 +371,8 @@ class Ata {
       for (const s of schema) this.addSchema(s);
       return this;
     }
-    const id = schema && typeof schema === 'object' && typeof schema.$id === 'string' ? schema.$id : undefined;
+    const id = schema && typeof schema === 'object' && typeof schema.$id === 'string' ? schema.$id
+      : isDraft4(schema) && 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) {
@@ -308,7 +449,11 @@ class Ata {
       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;
+    // A draft-04 schema is checked as the draft-07 schema it is read as: the
+    // boolean exclusive bounds in their numeric form, against draft-07's
+    // meta-schema (ata carries no draft-04 meta-schema).
+    if (isDraft4(schema)) schema = normalizeExclusiveBounds(structuredClone(draft4AsDraft7(schema)));
+    const declared = typeof schema.$schema === 'string' ? schema.$schema : typeof this.opts.defaultMeta === 'string' && !DRAFT4_IDS.has(this.opts.defaultMeta) ? this.opts.defaultMeta : DRAFT7;
     const metaId = METASCHEMAS.has(declared) ? declared : isDraft7Id(declared) ? DRAFT7 : DRAFT2020;
     const meta = metaValidator(metaId);
     const result = meta.validate(schema);
@@ -330,6 +475,15 @@ class Ata {
 
   addFormat(name, format) {
     this._formats[name] = formatToFunction(name, format);
+    // The reference applies a format declared `type: 'number'` to numbers,
+    // where JSON Schema, and ata, apply formats to strings only. Such a
+    // format is also checked on numbers here, by the interpreted engine (see
+    // compile).
+    if (format && typeof format === 'object' && format.type === 'number') {
+      this._numFormats = this._numFormats || Object.create(null);
+      this._numFormats[name] = this._formats[name];
+    } else if (this._numFormats) delete this._numFormats[name];
+    this._touchRegistry();
     this._compiled = new WeakMap();
     return this;
   }
@@ -346,6 +500,12 @@ class Ata {
       keyword = kwdOrDef.keyword;
       definition = kwdOrDef;
     }
+    // The reference takes a list of names for one definition (the formats
+    // plugin registers formatMinimum and its kin that way).
+    if (Array.isArray(keyword)) {
+      for (const k of keyword) this.addKeyword({ ...definition, keyword: k });
+      return this;
+    }
     if (typeof keyword !== 'string' || keyword === '') {
       throw new Error('addKeyword: keyword must be a non-empty string');
     }
@@ -358,14 +518,28 @@ class Ata {
       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`);
+      // A keyword defined only as generated code cannot run here. It is
+      // registered as known and refused when a schema uses it (see compile),
+      // so a library that defines such keywords for options it may never use
+      // can still take this class, and a schema that relies on one is never
+      // accepted without the check.
+      this._codeOnly = this._codeOnly || Object.create(null);
+      this._codeOnly[keyword] = { name: keyword, types: null, validate: null, compile: null, macro: null };
+      this._compiled = new WeakMap();
+      return this;
     }
     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.compile === 'function') mapped.compile = compileWithContext(definition.compile);
     if (typeof definition.macro === 'function') mapped.macro = definition.macro;
+    if (typeof definition.before === 'string') mapped.before = definition.before;
+    if (definition.post === true) mapped.post = true;
     if (mapped.validate && mapped.compile) delete mapped.validate;
+    // The reference hands every keyword function the data's context
+    // (parentData, parentDataProperty, instancePath, rootData), and keywords
+    // that remove or rewrite the value they check rely on it.
+    if (mapped.validate || mapped.compile) mapped.dataContext = true;
     this._keywords[keyword] = mapped;
     this._keywordDefs = this._keywordDefs || Object.create(null);
     this._keywordDefs[keyword] = definition;
@@ -386,6 +560,7 @@ class Ata {
 
   removeKeyword(keyword) {
     delete this._keywords[keyword];
+    if (this._codeOnly) delete this._codeOnly[keyword];
     if (this._keywordDefs) delete this._keywordDefs[keyword];
     this._compiled = new WeakMap();
     return this;
@@ -399,11 +574,121 @@ class Ata {
   }
 }
 
+// A reference keyword's compile(schema, parentSchema, it) returns a function
+// of (data, dataCxt). `it.schemaPath.str` is read by keywords that build their
+// own error objects, at the time they fail: it names the schema the check
+// sits in, which is known per call here, so it is read from the context the
+// call was given.
+function compileWithContext(compile) {
+  return (value, parentSchema) => {
+    let current = '#';
+    const it = { get schemaPath() { return { str: current }; } };
+    const inner = compile(value, parentSchema, it);
+    if (typeof inner !== 'function') return inner;
+    const wrapped = (data, ctx) => {
+      if (ctx && typeof ctx.schemaPath === 'string') current = ctx.schemaPath.slice(0, ctx.schemaPath.lastIndexOf('/')) || '#';
+      return inner(data, ctx);
+    };
+    // Errors the keyword writes land on its own function, read from here.
+    wrapped.source = inner;
+    return wrapped;
+  };
+}
+
+// The reference writes an error's fields as instancePath, schemaPath,
+// keyword, params, message; code that serializes errors sees the order. The
+// errors a custom keyword reports come out in another, and are put in this one.
+const REFERENCE_FIELDS = ['instancePath', 'schemaPath', 'keyword', 'params', 'message'];
+function inReferenceOrder(errors) {
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    if (e === null || typeof e !== 'object') continue;
+    const keys = Object.keys(e);
+    let ordered = true;
+    for (let j = 0; j < REFERENCE_FIELDS.length && j < keys.length; j++) if (keys[j] !== REFERENCE_FIELDS[j]) { ordered = false; break; }
+    if (ordered) continue;
+    const out = {};
+    for (const k of REFERENCE_FIELDS) if (k in e) out[k] = e[k];
+    for (const k of keys) if (!(k in out)) out[k] = e[k];
+    errors[i] = out;
+  }
+  return errors;
+}
+
+// useDefaults the way the reference applies it: in the properties of every
+// subschema the data is validated against outside anyOf, oneOf, not and if,
+// which includes those behind `allOf` and a `$ref`. ata's own pass fills the
+// `properties` it can reach by nesting alone; this one, run before it, also
+// goes through `allOf` and `$ref`. Both fill only a key the object does not
+// have, so what one fills the other leaves. Null when the schema has no
+// default anywhere such a walk could reach that ata's own pass would not.
+function referencedDefaults(rootDoc, registry) {
+  if (rootDoc === null || typeof rootDoc !== 'object') return null;
+  const f = features(rootDoc);
+  if ((f & F_DEFAULT) === 0 && !Object.values(registry || {}).some((d) => features(d) & F_DEFAULT)) return null;
+  if ((f & (F_REF | F_ALLOF)) === 0) return null;
+  const resolve = (ref) => {
+    const hash = ref.indexOf('#');
+    const base = hash < 0 ? ref : ref.slice(0, hash);
+    const doc = base === '' ? rootDoc : registry && registry[base];
+    if (doc === undefined || doc === null) return null;
+    const frag = hash < 0 ? '' : ref.slice(hash + 1);
+    if (frag !== '' && !frag.startsWith('/')) return null;
+    let node = doc;
+    for (const raw of frag === '' ? [] : frag.slice(1).split('/')) {
+      let seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+      try { seg = decodeURIComponent(seg); } catch { return null; }
+      if (node === null || typeof node !== 'object' || !Object.prototype.hasOwnProperty.call(node, seg)) return null;
+      node = node[seg];
+    }
+    return node;
+  };
+  const fill = (schema, data, active) => {
+    if (schema === null || typeof schema !== 'object' || data === null || typeof data !== 'object' || active.has(schema)) return;
+    active.add(schema);
+    if (typeof schema.$ref === 'string') fill(resolve(schema.$ref), data, active);
+    if (Array.isArray(schema.allOf)) for (const sub of schema.allOf) fill(sub, data, active);
+    const props = schema.properties;
+    if (props !== null && typeof props === 'object' && !Array.isArray(data)) {
+      for (const key of Object.keys(props)) {
+        const prop = props[key];
+        if (prop === null || typeof prop !== 'object') continue;
+        if (prop.default !== undefined && !Object.hasOwn(data, key)) {
+          const value = prop.default !== null && typeof prop.default === 'object' ? JSON.parse(JSON.stringify(prop.default)) : prop.default;
+          Object.defineProperty(data, key, { value, writable: true, enumerable: true, configurable: true });
+        }
+        // Into the value with a fresh set: the same schema may apply again
+        // one level down, in a recursive one.
+        if (Object.hasOwn(data, key)) fill(prop, data[key], new Set());
+      }
+    }
+    if (Array.isArray(data) && schema.items !== null && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+      for (const item of data) fill(schema.items, item, new Set());
+    }
+    active.delete(schema);
+  };
+  return (data) => fill(rootDoc, data, new Set());
+}
+
+// The registry id a fragment-only key is kept under: a `#...` string is not an
+// id a document can be found by, so it is given one.
+function fragmentKey(key) {
+  return key.startsWith('#') ? 'ata-compat:fragment:' + encodeURIComponent(key.slice(1)) : key;
+}
+
+
+// What a schema holds anywhere below it, read from the walk normalization
+// makes of it anyway (lib/schema-scan.js), which remembers it per object.
+const _scan = require('./lib/schema-scan');
+const F_BEYOND = _scan.BEYOND_ITEMS, F_DISCR = _scan.DISCRIMINATOR, F_DEFAULT = _scan.HAS_DEFAULT;
+const F_REF = _scan.HAS_REF, F_ALLOF = _scan.HAS_ALLOF, F_FORMAT = _scan.HAS_FORMAT;
+const features = _scan.scan;
+
 const _metaValidators = new Map();
 function metaValidator(id) {
   let v = _metaValidators.get(id);
   if (!v) {
-    v = new Validator({ $ref: id }, { useDefaults: false });
+    v = new Validator({ $ref: id }, { useDefaults: false, engine: 'interpreter' });
     _metaValidators.set(id, v);
   }
   return v;

package/index.bundle.mjs

@@ -0,0 +1,15 @@
+// ESM entry for bundlers that target a server (Bun, esbuild or Rollup for
+// Node) and for Node before 22.10, which does not match `module-sync`: the
+// validator core with the code generator registered, as index.js, but with
+// each tool imported on its own (lib/tools.mjs), so the tools an application
+// does not import stay out of its bundle. Through index.js a bundler sees one
+// CommonJS module and keeps all of them.
+import core from './lib/validator-core.js';
+import engine from './lib/codegen-engine.js';
+import { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } from './lib/tools.mjs';
+
+core._registerCodegen(engine);
+
+export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, defineSchema } = core;
+export { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };
+export default { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };

package/lib/aot-impl.js

@@ -251,7 +251,7 @@ function onePassCore(validator, opts) {
   const decls = [];
   const args = [];
   const own = new Set();
-  const addOwn = (n) => { if (own.has(n)) return; own.add(n); if (n === '_h' || n === '_hall') addOwn('_hop'); if (n === '_ok') { addOwn('_PN'); addOwn('_hop'); } decls.push(OWN_HELPER_CODE[n]); };
+  const addOwn = (n) => { if (own.has(n)) return; own.add(n); if (n === '_h' || n === '_hall') addOwn('_hop'); if (n === '_ok') { addOwn('_PN'); addOwn('_hop'); } if (n === '_nk') addOwn('_PN'); decls.push(OWN_HELPER_CODE[n]); };
   let usesSafeRe = emit.usesSafeRe, usesCollapse = false;
   for (let i = 0; i < emit.names.length; i++) {
     const name = emit.names[i], val = emit.values[i];
@@ -272,7 +272,7 @@ function onePassCore(validator, opts) {
     if (name === '_VF') { args.push('null'); continue; }
     if (name === '_PN') { addOwn('_PN'); args.push('_PN'); continue; }
     if (name === '_OP' || name === '_gp') { addOwn('_PN'); args.push(name); continue; }
-    if (name === '_hop' || name === '_h' || name === '_ok' || name === '_hall') { addOwn(name); args.push(name); continue; }
+    if (name === '_hop' || name === '_h' || name === '_ok' || name === '_hall' || name === '_nk') { addOwn(name); args.push(name); continue; }
     if (name === '_pe') { decls.push(PTR_ESC_HELPER); args.push('_pe'); continue; }
     if (name === '_deq') { decls.push(DEQ_HELPER); args.push('_deq'); continue; }
     if (name === '_anT') { decls.push('function _anT(){return true}'); args.push('_anT'); continue; }

package/lib/combined-runtime.js

@@ -121,6 +121,9 @@ const _hop = Object.prototype.hasOwnProperty
 function _h (o, k) { return _hop.call(o, k) }
 function _ok (o, k) { return (_PN ? o.__proto__ : _gp(o)) === _OP || _hop.call(o, k) } // eslint-disable-line no-proto
 function _hall (o, ks) { for (let i = 0; i < ks.length; i++) if (!_hop.call(o, ks[i])) return false; return true }
+// A key count that came out wrong, counted again over own keys unless the
+// object is ordinary.
+function _nk (o, n) { return (_PN ? o.__proto__ : _gp(o)) === _OP || Object.keys(o).length !== n } // eslint-disable-line no-proto
 
 // RFC 6901 escaping for a key only known at run time (the static ones are
 // escaped when the code is written).
@@ -140,7 +143,7 @@ function _rb (S, m) { if (S.length !== m) S.length = m }
 
 module.exports = {
   apState, ap, sr, srX, multiBranch,
-  _PN, _OP, _gp, _hop, _h, _ok, _hall, _pe, _anT, _anF, _rb,
+  _PN, _OP, _gp, _hop, _h, _ok, _hall, _nk, _pe, _anT, _anF, _rb,
 }
 // Loaded when a program first asks for them: a schema without const, enum,
 // uniqueItems, oneOf or anyOf never needs these modules on its cold path.