ata-validator 1.7.4 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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.8.1 - 2026-08-27
+
+### Changed
+
+- Constructing a validator no longer clones and serializes every schema to find out whether it needed normalizing. It did that on the root and on each registered schema: serialize, deep clone, normalize the clone, serialize again, compare. For a schema with no `nullable` field and no draft-07 keyword the answer is always no, and the work was thrown away. Every question the normalizers ask is whether some key appears anywhere in the tree, so one walk answers all of them, and the clone now happens only for schemas that need it. No registry and ten fields goes from 18.5 to 4.6 µs; fifty registered schemas of fifty fields, which is a small server's worth, from 2570 to 260 µs.
+
+  The walk descends through every object-valued key rather than the subschema keywords the normalizers recurse through, so it is a superset of what they visit: it can report work where there is none, costing one clone, and cannot miss work there is. Across the 2344 schemas in the official suite it reports work on 335 where normalization changes 334. `tests/test_schema_scan.js` asserts that direction over the whole suite, and asserts the check is load-bearing by breaking the scan deliberately and confirming the broken one is caught.
+
+  The answer is remembered against the schema object, the way whole compiled validators already are, and so is the schema map built from a registry. Both were being redone once per validator, so a server building one validator per route over a shared registry paid for that registry once per route. Fifty routes over twenty shared schemas boots in 0.046 ms rather than 20.66 ms. Validators share the map, and anything that writes to one, which is `addSchema()` and the meta-schema registration during compilation, takes a private copy first.
+
+  Nothing about what any schema validates to changes. The comparison that decided the old answer is still there behind the walk, so a schema the walk sends down the slow path gets exactly the result it got before.
+
+## 1.8.0 - 2026-08-27
+
+### Added
+
+- `$vocabulary` is honoured when a schema names a custom meta-schema in `$schema`. A dialect is a set of vocabularies and a vocabulary is a set of keywords, so a keyword whose vocabulary the meta-schema does not declare is not part of that dialect at all: it is an unknown keyword, and an unknown keyword is ignored. A schema written against a meta-schema which declares only the core and applicator vocabularies now has its `minimum`, `type` and the rest of the validation keywords ignored, while `properties` and the other applicators still apply. The keywords belonging to each vocabulary are read from the vendored meta-schemas rather than from a list kept by hand, so they come from the specification. Removing the keyword before compilation means every engine agrees without any of them knowing what a vocabulary is.
+
+  This closes the last case ata missed. Draft 2020-12 goes from 1298 to **1299 of 1299**, with draft 7 at 927 of 927 and the v1 dialect at 1133 of 1133, the same with code generation blocked. `tests/run_suite.js` has no known failures left.
+
+  Two things it does not do. It does not refuse a schema whose meta-schema requires, with `true`, a vocabulary ata does not recognise; the specification says an implementation must refuse there, and turning what has always been silently accepted into a hard failure is a separate decision, so such a schema is evaluated as before with every keyword applied. And a separate document reached through `$ref` keeps its own keywords rather than inheriting the referring dialect, so a document which should follow one needs to say so with its own `$schema`.
+
+### Fixed
+
+- `bundleStandalone` and `bundleCompact` built the error-reporting function from the schema the caller passed rather than the one the validator compiled. Anything which prepares a schema therefore reached the boolean path and not the error path: with `assertFormat: false` the bundle reported a `format` error the caller had turned off, and only once some other keyword failed first, since the error function runs only after the boolean one says no. `toStandalone` already read the compiled schema; these two now do as well.
+
 ## 1.7.4 - 2026-08-26
 
 ### Fixed
@@ -10,7 +36,7 @@ All notable changes to ata-validator are documented here. The format follows [Ke
 
 ### Changed
 
-- Rejecting a document through the buffer APIs no longer costs more than accepting one. The On-Demand plan answers first, and a `false` from it used to be ambiguous: it could mean the document failed a constraint, or that the plan could not decide. The caller had to assume the second, so it re-created the padded view, parsed the whole document again into a DOM, tried the generated plan, and then walked the tree. A rejected document was therefore parsed twice and walked up to three times. The plan now reports whether it stopped because the document failed a constraint or because it could not be read, and only the second falls through. simdjson's `INCORRECT_TYPE` is a constraint failure rather than a read failure, which is the distinction that makes this work: a property holding a string where the schema wants an integer surfaces as a read error from `get<int64>`, not as a type mismatch. On a 62 KB array of a thousand objects with one bad element: 316 µs to 11 µs when the bad element is first, 315 µs to 40 µs when it is last, and rejecting is now never dearer than accepting. `tests/test_buffer_path_parity.js` holds the buffer path to the same answers as `validate()` across all 3359 suite cases, and still reports zero disagreements.
+- Rejecting a document through the buffer APIs no longer costs more than accepting one. The On-Demand plan answers first, and a `false` from it used to be ambiguous: it could mean the document failed a constraint, or that the plan could not decide. The caller had to assume the second, so it re-created the padded view, parsed the whole document again into a DOM, tried the generated plan, and then walked the tree. A rejected document was therefore parsed twice and walked up to three times. The plan now reports whether it stopped because the document failed a constraint or because it could not be read, and only the second falls through. simdjson's `INCORRECT_TYPE` is a constraint failure rather than a read failure, which is the distinction that makes this work: a property holding a string where the schema wants an integer surfaces as a read error from `get<int64>`, not as a type mismatch. On a 62 KB array of a thousand objects with one bad element: 316 µs to 11 µs when the bad element is first, 315 µs to 40 µs when it is last. On that shape rejecting is no longer dearer than accepting, and when the bad element is early it is several times cheaper. It is still dearer on a small document, where there is no bulk of parsing for an early exit to save: on a two-field object, 129 ns to accept and 278 ns to reject. `tests/test_buffer_path_parity.js` holds the buffer path to the same answers as `validate()` across all 3359 suite cases, and still reports zero disagreements.
 
 ## 1.7.3 - 2026-08-26
 

package/README.md

@@ -14,17 +14,29 @@ npm install --save-dev ata-validator
 npx ata build 'schemas/*.json' --out-dir src/generated
 ```
 
-The `ata-validator` package itself is pure JavaScript. The native accelerator (simdjson parsing, parallel NDJSON, buffer APIs) ships as per-platform optional packages that npm installs automatically where they fit, the same pattern Vite uses for esbuild. For a guaranteed zero-binary install:
+The `ata-validator` package itself is pure JavaScript. The native accelerator (simdjson parsing, parallel NDJSON, buffer APIs) ships as per-platform optional packages that npm installs automatically where they fit, the same pattern Vite uses for esbuild. Seven targets are built: macOS on arm64 and x64, Linux on x64 and arm64 against both glibc and musl, and Windows on x64. A platform without a prebuild still installs and validates, on the pure-JS engine. For a guaranteed zero-binary install:
 
 ```bash
 npm install ata-validator --omit=optional
 ```
 
-or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1298 of 1299 Draft 2020-12 cases; the one case both miss needs `$vocabulary`, which ata does not implement. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
+or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1299 of 1299 Draft 2020-12 cases. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
 
 Those four now agree with `validate()` on every case of the official suite, 3359 across three dialects. The native walker behind them does not handle every shape (`contains`, `unevaluatedProperties`, `patternProperties`, tuple `items`, cross-document `$ref`, a few formats), so for schemas using one of those the buffer APIs parse the bytes and answer through `validate()`; the list is in `lib/buffer-gate.js`. Typical request schemas stay on the zero-copy path. `npm test` holds the disagreement count at zero.
 
-Where `new Function` is refused altogether, on Cloudflare Workers, Deno Deploy or under a strict Content-Security-Policy, ata drops to the interpreted engine and scores the same 1298 of 1299 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
+Where `new Function` is refused altogether, on Cloudflare Workers, Deno Deploy or under a strict Content-Security-Policy, ata drops to the interpreted engine and scores the same 1299 of 1299 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
+
+Node has a switch for exactly that environment, so this takes thirty seconds to check for yourself, on ata or on whatever you use today:
+
+```bash
+node --disallow-code-generation-from-strings -e "
+  const { Validator } = require('ata-validator')
+  const v = new Validator({ type: 'object', properties: { id: { type: 'integer' } }, required: ['id'] })
+  console.log(v.validate({ id: 1 }).valid, v.validate({ id: 'x' }).valid)
+"
+```
+
+A validator that reaches its speed by generating source and calling `new Function` cannot run under that flag at all, which is the same reason it cannot run on a Worker. That is a deliberate trade rather than an oversight, and it is worth knowing which side of it your validator is on before you deploy to an edge runtime.
 
 In your code:
 
@@ -428,7 +440,7 @@ const result = v['~standard'].validate(data);
 
 ### Fastify Plugin
 
-Measured against Fastify's own schema and validation test files with ata swapped in as the default validator: 181 of 187 tests pass, and the remaining six assert the default validator's own extension API rather than validation behavior. Validation errors follow the schema's keyword declaration order, so error-message plugins and `transformErrors` hooks written against the default validator see the same order.
+Measured against Fastify's own schema and validation test files with ata swapped in as the default validator: 178 of 184 tests pass, and the remaining six assert the default validator's own extension API rather than validation behavior. Validation errors follow the schema's keyword declaration order, so error-message plugins and `transformErrors` hooks written against the default validator see the same order.
 
 ```bash
 npm install fastify-ata
@@ -507,12 +519,12 @@ Both are implemented in the interpreted engine, so a v1 schema that uses `$dynam
 
 ### Known limitations
 
-Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1298 of 1299 cases, 99.9%. Draft 7 gives 927 of 927. The v1 dialect gives 1133 of 1133. The one 2020-12 case that fails uses a custom meta-schema that drops the validation vocabulary through `$vocabulary`, which ata does not implement, so the validation keywords still apply. `npm run test:suite` reproduces all three and names it.
+Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1299 of 1299 cases. Draft 7 gives 927 of 927. The v1 dialect gives 1133 of 1133. `npm run test:suite` reproduces all three.
 
 Areas that remain deliberate scope decisions for 1.x:
 
 - **Remote `$ref` over the network** is not fetched. Register cross-schema refs explicitly with `schemas: [...]` or `addSchema()`.
-- **`$vocabulary`** is not implemented; custom vocabularies are ignored rather than enforced. The keyword was extracted from the specification for the stable release as incomplete, so it is not part of v1.
+- **`$vocabulary`** is honoured for the document which names the meta-schema: a keyword whose vocabulary that meta-schema does not declare is not part of the dialect, so it is treated as unknown and does not apply. Two things it does not do. It does not refuse a schema whose meta-schema requires a vocabulary ata does not recognise, which the specification says an implementation must do; that schema is evaluated with every keyword applied, as before. And a separate document reached through `$ref` keeps its own keywords rather than inheriting the referring dialect, so register it with its own `$schema` if it should follow one.
 - **`contentEncoding` / `contentMediaType` / `contentSchema`** are annotation-only, as the spec permits, and are not validated.
 - **`minLength`/`maxLength`** count UTF-16 code units, not grapheme clusters.
 - **Infinite-loop detection** relies on a recursion depth guard that cuts off circular `$ref` chains.

package/index.js

@@ -10,6 +10,8 @@ const {
   compileToJSCombined,
 } = require("./lib/js-compiler");
 const { normalizeDraft7, normalizeNullable, stripFormatAssertions } = require("./lib/draft7");
+const { enabledKeywords, stripDisabledKeywords } = require("./lib/vocabularies");
+const { needsNormalization } = require("./lib/schema-scan");
 const { isV1Dialect } = require("./lib/dialect");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
@@ -459,11 +461,20 @@ function _normalizeCallerSchema(s, inheritDraft7) {
   const needsDraft7 = declares
     ? (s.$schema === 'http://json-schema.org/draft-07/schema#' || s.$schema === 'http://json-schema.org/draft-07/schema')
     : !!inheritDraft7
+  // One walk answers whether there is anything to do. Almost always there is
+  // not, and then the serialize, clone, normalize, serialize, compare below is
+  // work spent to find that out. The walk over-reports rather than under, so a
+  // schema it clears is one no normalizer would have touched;
+  // `tests/test_schema_scan.js` holds that direction against the whole suite.
+  if (!needsNormalization(s, needsDraft7)) return s
+
   const str = JSON.stringify(s)
   const copy = _deepCloneWithSymbols(s)
   if (needsDraft7) normalizeDraft7(copy, true)
   normalizeNullable(copy)
   // Return original when normalization produced no change, copy otherwise.
+  // Kept even though the walk has already said there is work, so that a walk
+  // which over-reports still returns exactly what it returned before.
   // Change-detection uses JSON content only; symbols do not affect it.
   return JSON.stringify(copy) === str ? s : copy
 }
@@ -487,8 +498,33 @@ function declaredId(original, normalized) {
 
 // `inheritDraft7` is true when the root schema is draft-07: a retrieved
 // document that declares no dialect is read under the root's draft.
+// The map is derived entirely from what the caller passed, so the same
+// `schemas` gives the same map. A server building one validator per route over
+// a shared registry rebuilt it once per route, normalizing and re-reading the
+// `$id` of every registered schema each time. Keyed by the registry object,
+// and by the draft it is read under, since that changes what normalization
+// does to a document which declares no dialect of its own.
+//
+// Validators share the returned map, so anything that mutates one calls
+// `_ownSchemaMap()` first. There are two such places: registering the vendored
+// meta-schemas during compilation, and `addSchema()`.
+const _schemaMapCache = new WeakMap()
+
 function buildSchemaMap(schemas, inheritDraft7) {
   if (!schemas) return null
+  const byDraft = _schemaMapCache.get(schemas)
+  if (byDraft) {
+    const hit = byDraft[inheritDraft7 ? 1 : 0]
+    if (hit) return hit
+  }
+  const map = _buildSchemaMap(schemas, inheritDraft7)
+  const slot = byDraft || [null, null]
+  slot[inheritDraft7 ? 1 : 0] = map
+  if (!byDraft) _schemaMapCache.set(schemas, slot)
+  return map
+}
+
+function _buildSchemaMap(schemas, inheritDraft7) {
   const map = new Map()
   if (Array.isArray(schemas)) {
     for (const s of schemas) {
@@ -511,6 +547,29 @@ function buildSchemaMap(schemas, inheritDraft7) {
   return map
 }
 
+// A schema which names a custom meta-schema in `$schema` is written against
+// whatever dialect that meta-schema declares. A keyword from a vocabulary the
+// dialect does not have is not part of the dialect, so it is an unknown
+// keyword and does not apply. Removing it here means every engine sees the
+// same schema and none of them needs to know about vocabularies.
+//
+// Only the root is consulted. A subschema naming its own `$schema` is its own
+// resource under its own dialect, and the walk stops there rather than
+// applying this dialect's answer to it.
+function _applyVocabularies(schemaObj, original, schemaMap) {
+  if (!schemaObj || typeof schemaObj !== 'object') return schemaObj
+  const declared = schemaObj.$schema
+  if (typeof declared !== 'string') return schemaObj
+  const enabled = enabledKeywords(schemaMap.get(declared))
+  if (!enabled) return schemaObj
+  // `original` is the caller's own object when it reached here unchanged, and
+  // that one is never mutated.
+  const copy = schemaObj === original
+    ? _deepCloneWithSymbols(schemaObj)
+    : schemaObj
+  return stripDisabledKeywords(copy, enabled)
+}
+
 // Compile-cache key for a root schema plus its external schemas. Must include
 // the external schema CONTENT, not just their $ids: two validators can share a
 // root schema string and the same $id while pointing that $id at different
@@ -621,6 +680,15 @@ class Validator {
       );
     }
 
+    // Built here rather than below because `$vocabulary` is resolved against
+    // it, and that resolution waits until compilation so a meta-schema
+    // registered by addSchema() still counts.
+    const shared = buildSchemaMap(options.schemas, rootIsDraft7);
+    const schemaMap = shared || new Map();
+    this._schemaMapShared = shared !== null;
+    this._schemaIsCallers = schemaObj === schema;
+    this._vocabulariesApplied = false;
+
     this._schemaStr = null; // lazy: computed on first use
     this._schemaObj = schemaObj;
     this._options = options;
@@ -634,7 +702,7 @@ class Validator {
     this._applyDefaults = null;
 
     // Schema map for cross-schema $ref resolution
-    this._schemaMap = buildSchemaMap(options.schemas, rootIsDraft7) || new Map();
+    this._schemaMap = schemaMap;
 
     // User-supplied format checkers: { formatName: (value) => boolean }.
     // Looked up at runtime when a schema references a format the built-in
@@ -758,8 +826,27 @@ class Validator {
     }
   }
 
+  // `$vocabulary` says which keywords the dialect has, and answering needs the
+  // meta-schema, which addSchema() may only have registered just now. Run once,
+  // before anything reads the schema, and before `_schemaStr` is computed from
+  // it. After this addSchema() is refused, so the answer cannot go stale.
+  _ensureVocabularies() {
+    if (this._vocabulariesApplied) return;
+    this._vocabulariesApplied = true;
+    const stripped = _applyVocabularies(
+      this._schemaObj,
+      this._schemaIsCallers ? this._schemaObj : null,
+      this._schemaMap,
+    );
+    if (stripped !== this._schemaObj) {
+      this._schemaObj = stripped;
+      this._schemaStr = null;
+    }
+  }
+
   _ensureCompiled() {
     if (this._initialized) return;
+    this._ensureVocabularies();
     this._initialized = true;
 
     const schemaObj = this._schemaObj;
@@ -774,6 +861,7 @@ class Validator {
     // reference pay for the lookup.
     if (this._schemaStr.includes('json-schema.org/draft')) {
       const { METASCHEMAS } = require('./lib/metaschemas');
+      this._ownSchemaMap();
       for (const [id, meta] of METASCHEMAS) {
         const bare = id.replace(/#$/, '');
         for (const key of [id, bare, bare + '#', bare.replace(/^https:/, 'http:'), bare.replace(/^http:/, 'https:')]) {
@@ -1482,11 +1570,21 @@ class Validator {
     const rootIsDraft7 = !!(root && typeof root === 'object' && typeof root.$schema === 'string' &&
       (root.$schema === 'http://json-schema.org/draft-07/schema#' || root.$schema === 'http://json-schema.org/draft-07/schema'))
     const normalized = _normalizeCallerSchema(schema, rootIsDraft7)
+    this._ownSchemaMap()
     this._schemaMap.set(normalized.$id, normalized)
   }
 
+  // buildSchemaMap hands the same map to every validator built from the same
+  // registry. Take a private copy before writing to it.
+  _ownSchemaMap() {
+    if (!this._schemaMapShared) return
+    this._schemaMap = new Map(this._schemaMap)
+    this._schemaMapShared = false
+  }
+
   _ensureCodegen() {
     if (this._jsFn) return;
+    this._ensureVocabularies();
     if (typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI) return;
     if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;

package/lib/aot.js

@@ -285,8 +285,13 @@ function bundleStandalone(Validator, schemas, opts) {
     v._ensureCompiled();
     const jsFn = v._jsFn;
     if (!jsFn || !jsFn._hybridSource) return 'null';
+    // The schema the validator compiled, not the one the caller passed. They
+    // differ whenever anything prepared the schema: draft-07 normalization,
+    // `format` removed under assertFormat: false, keywords outside the
+    // dialect's vocabularies. Reading the original here would leave the
+    // boolean path and the error path disagreeing about the same document.
     const jsErrFn = compileToJSCodegenWithErrors(
-      typeof schema === 'string' ? JSON.parse(schema) : schema,
+      v._schemaObj,
       v._schemaMap,
       v._userFormats,
     );
@@ -311,7 +316,7 @@ function bundleStandalone(Validator, schemas, opts) {
     }
     if (opts && opts.verbose) {
       // Embed the schema and a small resolver so errors carry parentSchema.
-      const schemaLit = JSON.stringify(typeof schema === 'string' ? JSON.parse(schema) : schema);
+      const schemaLit = JSON.stringify(v._schemaObj);
       return `(function(R){${preamble}var _S=${schemaLit};function _PS(p){if(!p||p[0]!=='#')return undefined;var s=p.slice(1);if(!s)return _S;var ps=s.split('/').filter(Boolean).map(function(x){return x.replace(/~1/g,'/').replace(/~0/g,'~')});var t=_S;for(var i=0;i<ps.length-1;i++){if(t==null||typeof t!=='object')return undefined;t=t[ps[i]]}return t}var E=function(d){var _all=true;${errBody}};var _v=function(d){${jsFn._hybridSource}};return function(d){var r=_v(d);if(r&&r.valid===false&&r.errors){var es=[];for(var i=0;i<r.errors.length;i++){var e=r.errors[i];es.push(Object.assign({},e,{parentSchema:_PS(e.schemaPath)}))}return{valid:false,errors:es}}return r}})(R)`;
     }
     return `(function(R){${preamble}var E=function(d){var _all=true;${errBody}};return function(d){${jsFn._hybridSource}}})(R)`;
@@ -343,8 +348,13 @@ function bundleCompact(Validator, schemas, opts) {
     v._ensureCompiled();
     const jsFn = v._jsFn;
     if (!jsFn || !jsFn._hybridSource) return null;
+    // The schema the validator compiled, not the one the caller passed. They
+    // differ whenever anything prepared the schema: draft-07 normalization,
+    // `format` removed under assertFormat: false, keywords outside the
+    // dialect's vocabularies. Reading the original here would leave the
+    // boolean path and the error path disagreeing about the same document.
     const jsErrFn = compileToJSCodegenWithErrors(
-      typeof schema === 'string' ? JSON.parse(schema) : schema,
+      v._schemaObj,
       v._schemaMap,
       v._userFormats,
     );

package/lib/schema-scan.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// One walk of a schema, answering in a single integer the questions that are
+// currently answered by doing work and looking at the result.
+//
+// `_normalizeCallerSchema` decides whether a schema needs normalizing by
+// serializing it, cloning it, normalizing the clone and serializing again to
+// compare. Two serializations and a deep copy, on every schema, to find out
+// that a modern schema needs nothing. The questions the normalizers actually
+// ask are all of the form "does this key appear anywhere in the tree", and one
+// traversal answers all of them at once. Daniel Lemire's rule from the C++
+// side, a layer up: do not do the work to find out whether the work is needed.
+//
+// The walk deliberately descends through **every** object-valued key, not the
+// list of subschema keywords the normalizers recurse through. That makes it a
+// superset of what they visit, so it can report work where there is none, but
+// never miss work there is. A false positive costs one clone. A false negative
+// would hand an un-normalized schema to the engines, which is the silent
+// acceptance this codebase treats as its worst failure. `tests/test_schema_scan.js`
+// pins the direction of that error against the whole suite.
+
+// One bit per question. Kept small and explicit; a schema which trips none of
+// them scans to 0 and can skip normalization entirely.
+const NULLABLE = 1 << 0;         // `nullable`, which normalizeNullable folds into `type`
+const REF_SIBLINGS = 1 << 1;     // a draft-07 `$ref` carrying keywords which are ignored
+const ANCHOR_ID = 1 << 2;        // a fragment-only `$id`, which is an anchor in draft-07
+const DEFINITIONS = 1 << 3;      // `definitions`, renamed to `$defs`
+const DEPENDENCIES = 1 << 4;     // `dependencies`, split into two keywords
+const TUPLE_ITEMS = 1 << 5;      // array-valued `items`, split into `prefixItems`
+
+// Everything only draft-07 normalization acts on. A schema of another dialect
+// can carry these without them meaning anything, so they are read together
+// with whether the document is draft-07 at all.
+const DRAFT7_WORK = REF_SIBLINGS | ANCHOR_ID | DEFINITIONS | DEPENDENCIES | TUPLE_ITEMS;
+
+// Copied from the normalizer rather than shared, so that a change there which
+// forgets this file shows up as a differential test failure rather than as a
+// silently wider scan. The test asserts the two agree.
+const REF_SIBLINGS_KEPT = new Set([
+  '$ref', '$defs', 'definitions', '$schema', '$comment',
+  'title', 'description', 'examples', 'default', 'readOnly', 'writeOnly',
+]);
+const ANCHOR_ID_RE = /^#[A-Za-z][A-Za-z0-9_.:-]*$/;
+
+// The answer depends only on the object, so it is remembered against it. A
+// server building one validator per route over a shared registry hands the
+// same registry objects to every one of them: fifty routes over twenty shared
+// schemas scanned those twenty a thousand times. Identity caching is what
+// `_identityCache` already does for whole compiled validators.
+//
+// This assumes a schema is not mutated after being handed to a Validator,
+// which is already true of everything else here: the compile cache, the
+// identity cache and the schema map would all be stale too.
+const CACHE = new WeakMap();
+
+function scan(schema) {
+  if (typeof schema !== 'object' || schema === null) return 0;
+  const hit = CACHE.get(schema);
+  if (hit !== undefined) return hit;
+
+  let bits = 0;
+  const seen = new Set();
+
+  const walk = (node) => {
+    if (typeof node !== 'object' || node === null) return;
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) walk(node[i]);
+      return;
+    }
+    if (seen.has(node)) return;
+    seen.add(node);
+
+    if ('nullable' in node) bits |= NULLABLE;
+    if (node.definitions !== undefined && node.$defs === undefined) bits |= DEFINITIONS;
+    if (node.dependencies !== undefined) bits |= DEPENDENCIES;
+    if (Array.isArray(node.items)) bits |= TUPLE_ITEMS;
+    if (typeof node.$id === 'string' && ANCHOR_ID_RE.test(node.$id)) bits |= ANCHOR_ID;
+
+    // `Object.keys` rather than `for...in`: the prototype chain has nothing
+    // to contribute here, and walking it is the slower path in V8.
+    const keys = Object.keys(node);
+    if (typeof node.$ref === 'string') {
+      for (let i = 0; i < keys.length; i++) {
+        if (!REF_SIBLINGS_KEPT.has(keys[i])) { bits |= REF_SIBLINGS; break; }
+      }
+    }
+    // Every key, not just the subschema keywords, so this cannot miss a place
+    // the normalizers would reach.
+    for (let i = 0; i < keys.length; i++) walk(node[keys[i]]);
+  };
+
+  walk(schema);
+  CACHE.set(schema, bits);
+  return bits;
+}
+
+// Would normalization change this schema? `isDraft7` says whether the draft-07
+// rules apply at all, which the caller already knows.
+function needsNormalization(schema, isDraft7) {
+  const bits = scan(schema);
+  if (bits & NULLABLE) return true;
+  return isDraft7 ? (bits & DRAFT7_WORK) !== 0 : false;
+}
+
+module.exports = {
+  scan,
+  needsNormalization,
+  NULLABLE,
+  REF_SIBLINGS,
+  ANCHOR_ID,
+  DEFINITIONS,
+  DEPENDENCIES,
+  TUPLE_ITEMS,
+  DRAFT7_WORK,
+};

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.7.4';
+module.exports = '1.8.1';

package/lib/vocabularies.js

@@ -0,0 +1,199 @@
+'use strict';
+
+// `$vocabulary`, as far as evaluation is concerned.
+//
+// A dialect is a set of vocabularies, and a vocabulary is a set of keywords.
+// When a schema names a custom meta-schema in `$schema`, that meta-schema's
+// `$vocabulary` says which vocabularies the dialect has. A keyword whose
+// vocabulary is not there is not part of the dialect at all, so it is an
+// unknown keyword, and an unknown keyword is ignored. Deleting it is exactly
+// that reading, and it means every engine gets this for free rather than each
+// of them growing a notion of vocabularies.
+//
+// The keyword lists are not written out here. Each official vocabulary has a
+// meta-schema whose `properties` are precisely that vocabulary's keywords,
+// and those documents are already vendored in `metaschemas.js`, so the lists
+// come from the specification rather than from someone keeping a copy in
+// step with it.
+//
+// What this deliberately does not do: refuse a schema whose meta-schema
+// requires a vocabulary ata does not know. The specification says an
+// implementation must refuse there, and ata does not, because until now it
+// ignored `$vocabulary` entirely and turning that into a hard failure would
+// break schemas which work today. Such a schema is left exactly as it was,
+// evaluated with every keyword applied. See `docs/` for the limitation.
+
+const { METASCHEMAS } = require('./metaschemas')
+
+const CORE_VOCABULARY = 'https://json-schema.org/draft/2020-12/vocab/core'
+
+// vocabulary URI -> Set of the keywords it defines, built once on first use.
+let KEYWORDS_BY_VOCABULARY = null
+
+function keywordsByVocabulary() {
+  if (KEYWORDS_BY_VOCABULARY) return KEYWORDS_BY_VOCABULARY
+  const byVocabulary = new Map()
+  for (const name of [
+    'core',
+    'applicator',
+    'unevaluated',
+    'validation',
+    'meta-data',
+    'format-annotation',
+    'content',
+  ]) {
+    const meta = METASCHEMAS.get(
+      `https://json-schema.org/draft/2020-12/meta/${name}`,
+    )
+    if (!meta || !meta.properties) continue
+    byVocabulary.set(
+      `https://json-schema.org/draft/2020-12/vocab/${name}`,
+      new Set(Object.keys(meta.properties)),
+    )
+  }
+  // The one vocabulary with no document to read. `format-assertion` is an
+  // alternative to `format-annotation` rather than part of the standard
+  // dialect, so its meta-schema is not among the vendored ones. It defines
+  // the single keyword `format`, which is what the other one defines, and a
+  // vocabulary's keyword set does not change once it is published. Without
+  // this a meta-schema asking for format assertion, which is the standard
+  // way to ask, would be a vocabulary ata does not know and no filtering
+  // would happen at all.
+  byVocabulary.set(
+    'https://json-schema.org/draft/2020-12/vocab/format-assertion',
+    new Set(['format']),
+  )
+
+  KEYWORDS_BY_VOCABULARY = byVocabulary
+  return byVocabulary
+}
+
+// Every keyword ata can attribute to a vocabulary. A keyword outside this set
+// belongs to no vocabulary ata knows, so `$vocabulary` says nothing about it
+// and it is left alone.
+function allVocabularyKeywords() {
+  const all = new Set()
+  for (const keywords of keywordsByVocabulary().values()) {
+    for (const keyword of keywords) all.add(keyword)
+  }
+  return all
+}
+
+// Given a meta-schema, the keywords a schema written against it may use, or
+// `null` when the question does not arise or cannot be answered:
+//
+//   - the document declares no `$vocabulary`, so it does not describe a
+//     dialect in these terms and every keyword stands
+//   - it requires a vocabulary ata does not know, so ata cannot say which
+//     keywords the dialect has and does not guess
+function enabledKeywords(metaschema) {
+  if (!metaschema || typeof metaschema !== 'object') return null
+  const vocabularies = metaschema.$vocabulary
+  if (!vocabularies || typeof vocabularies !== 'object') return null
+
+  const known = keywordsByVocabulary()
+  const enabled = new Set()
+  for (const [uri, required] of Object.entries(vocabularies)) {
+    const keywords = known.get(uri)
+    if (keywords) {
+      for (const keyword of keywords) enabled.add(keyword)
+    } else if (required === true) {
+      return null // a required vocabulary ata cannot account for
+    }
+  }
+
+  // Core is what makes a document a schema at all: `$ref`, `$defs`, `$id`.
+  // A meta-schema which omits it is not describing something ata could
+  // evaluate, so treat core as present rather than stripping the plumbing.
+  for (const keyword of known.get(CORE_VOCABULARY) || []) enabled.add(keyword)
+
+  // The usual case is a meta-schema which has every vocabulary, and then
+  // there is nothing to answer. Saying so here keeps the caller from copying
+  // a schema it would not have changed.
+  for (const keyword of allVocabularyKeywords()) {
+    if (!enabled.has(keyword)) return enabled
+  }
+  return null
+}
+
+// Delete every keyword which belongs to a vocabulary the dialect does not
+// have. Mutates, so callers pass a copy.
+function stripDisabledKeywords(schema, enabled) {
+  const removable = allVocabularyKeywords()
+  const disabled = new Set()
+  for (const keyword of removable) {
+    if (!enabled.has(keyword)) disabled.add(keyword)
+  }
+  if (disabled.size === 0) return schema
+  _strip(schema, disabled, new Set(), true)
+  return schema
+}
+
+function _strip(schema, disabled, seen, isRoot) {
+  if (typeof schema !== 'object' || schema === null) return
+  if (Array.isArray(schema)) {
+    for (const each of schema) _strip(each, disabled, seen, false)
+    return
+  }
+  if (seen.has(schema)) return
+  seen.add(schema)
+
+  // A subschema which names its own `$schema` is its own resource under its
+  // own dialect, so this dialect's vocabularies say nothing about it. The
+  // root names one by definition, which is how this dialect was chosen.
+  if (!isRoot && typeof schema.$schema === 'string') return
+
+  for (const keyword of disabled) {
+    if (keyword in schema) delete schema[keyword]
+  }
+
+  // Walk what is left. A disabled applicator has already been deleted, so
+  // this only descends through subschemas which still apply.
+  const objSubs = [
+    'properties',
+    'patternProperties',
+    '$defs',
+    'definitions',
+    'dependentSchemas',
+  ]
+  for (const key of objSubs) {
+    const box = schema[key]
+    if (box && typeof box === 'object' && !Array.isArray(box)) {
+      for (const each of Object.values(box)) _strip(each, disabled, seen, false)
+    }
+  }
+  const arrSubs = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+  for (const key of arrSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const each of schema[key]) _strip(each, disabled, seen, false)
+    }
+  }
+  const singleSubs = [
+    'items',
+    'additionalItems',
+    'contains',
+    'not',
+    'if',
+    'then',
+    'else',
+    'additionalProperties',
+    'propertyNames',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+    'contentSchema',
+  ]
+  for (const key of singleSubs) {
+    const sub = schema[key]
+    if (Array.isArray(sub)) {
+      for (const each of sub) _strip(each, disabled, seen, false)
+    } else {
+      _strip(sub, disabled, seen, false)
+    }
+  }
+}
+
+module.exports = {
+  enabledKeywords,
+  stripDisabledKeywords,
+  keywordsByVocabulary,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -44,7 +44,7 @@
     "release:check": "node scripts/regen-safe-regex-source.js && node tests/test_pack_purity.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
-    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7 && node tests/run_suite.js v1",
     "test:compat": "node tests/test_compat.js",
@@ -112,13 +112,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.7.4",
-    "@ata-validator/native-darwin-x64": "1.7.4",
-    "@ata-validator/native-linux-x64-gnu": "1.7.4",
-    "@ata-validator/native-linux-arm64-gnu": "1.7.4",
-    "@ata-validator/native-linux-x64-musl": "1.7.4",
-    "@ata-validator/native-linux-arm64-musl": "1.7.4",
-    "@ata-validator/native-win32-x64": "1.7.4"
+    "@ata-validator/native-darwin-arm64": "1.8.1",
+    "@ata-validator/native-darwin-x64": "1.8.1",
+    "@ata-validator/native-linux-x64-gnu": "1.8.1",
+    "@ata-validator/native-linux-arm64-gnu": "1.8.1",
+    "@ata-validator/native-linux-x64-musl": "1.8.1",
+    "@ata-validator/native-linux-arm64-musl": "1.8.1",
+    "@ata-validator/native-win32-x64": "1.8.1"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"