ata-validator 1.50.0 → 1.51.0

package/aot.d.ts

@@ -56,7 +56,17 @@ export function compactDecline(validator: Validator<unknown>): string | null;
  * runtime Validator does with `richErrors: false`. Null where
  * toCompactModule would be null. `ata build --mode schema` writes these.
  */
-export function toSchemaModule(validator: Validator<unknown>, opts: { runtime: string; format?: 'esm' | 'cjs' }): string | null;
+export function toSchemaModule(validator: Validator<unknown>, opts: { runtime: string; registry?: string; format?: 'esm' | 'cjs' }): string | null;
+
+/**
+ * Source of the registry module schema modules import when their schemas
+ * reference each other by `$id`: the schemas, without descriptive keywords,
+ * as one array. Pass its import specifier as `registry` to toSchemaModule,
+ * for a validator built with those schemas in its `schemas` option; the module
+ * then names its schema by `$id` and carries no copy of it. `ata build --mode
+ * schema` does this for inputs that reference each other.
+ */
+export function registrySource(schemas: ReadonlyArray<object | Validator<unknown>>, format?: 'esm' | 'cjs'): string;
 
 /** Source of the runtime compact modules (and, with `schemaMode`, schema
  * modules) import. With `schemas`, the validators or schemas whose modules

package/aot.mjs

@@ -1,3 +1,3 @@
 import mod from './lib/aot-impl.js';
-export const { toStandalone, toStandaloneModule, toCompactModule, toSchemaModule, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
+export const { toStandalone, toStandaloneModule, toCompactModule, toSchemaModule, registrySource, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
 export default mod;

package/bin/ata.js

@@ -51,6 +51,9 @@ Build options:
   --mode <mode>           code (default) | schema. schema writes each module as its
                           schema and takes the verdict and errors from one runtime
                           file: far smaller and quicker to load, slower per check
+  --base-uri <uri>        The URI an input without $id is known by: <uri> plus its
+                          file name, for schemas that reference a shared file by URL
+                          or relative path
   --check                 Check (don't write); exit 1 if any output is stale
   --cache-file <path>     Cache file for incremental builds (default: cache disabled)
   --max-size <bytes>      Fail build if any compiled module exceeds this gzipped size
@@ -102,6 +105,7 @@ function parseArgs(argv) {
     if (a === '--one-pass') { out.opts.onePass = true; continue; }
     if (a === '--errors') { out.opts.errors = argv[++i]; continue; }
     if (a === '--mode') { out.opts.mode = argv[++i]; continue; }
+    if (a === '--base-uri') { out.opts.baseUri = argv[++i]; continue; }
     if (a === '--check') { out.opts.check = true; continue; }
     if (a === '--strict') { out.opts.strict = true; continue; }
     if (a === '--strict-schema') { out.opts.strictSchema = true; continue; }
@@ -306,6 +310,7 @@ function cmdBuild(args) {
     onePass: args.opts.onePass === true ? true : undefined,
     errors: args.opts.errors,
     mode: args.opts.mode,
+    baseUri: args.opts.baseUri,
     check: !!args.opts.check,
     maxSize: args.opts.maxSize,
     strict: !!args.opts.strict,
@@ -326,6 +331,22 @@ function cmdBuild(args) {
     }
     if (report.runtime) {
       process.stdout.write(`ata: error runtime -> ${report.runtime.output} (${report.runtime.bytes.toLocaleString()} bytes, shared by the modules above)\n`);
+      if (report.runtime.registry) process.stdout.write(`ata: schema registry -> ${report.runtime.registry.output} (${report.runtime.registry.bytes.toLocaleString()} bytes, the schemas the modules above reference)\n`);
+    }
+    // A module the error generator declined still has an exact verdict, but
+    // every failure is the one ATA9000 error. Said once per module, short,
+    // and once with what to do about it.
+    let noDetail = 0;
+    for (const w of report.warnings || []) {
+      if (w.kind === 'error-detail') {
+        noDetail++;
+        process.stderr.write(`ata: warning ${w.input}: no error detail, failures report the single ATA9000 error (the verdict is exact)\n`);
+      } else {
+        process.stderr.write(`ata: warning ${w.input}: ${w.warning}\n`);
+      }
+    }
+    if (noDetail > 0 && args.opts.mode !== 'schema') {
+      process.stderr.write(`ata: ${noDetail} module${noDetail === 1 ? '' : 's'} without error detail; with --mode schema a module takes its errors from the interpreted engine instead\n`);
     }
     for (const c of report.cached) {
       process.stdout.write(`ata: cached  ${c.input}\n`);

package/lib/aot-build.js

@@ -109,6 +109,99 @@ function importSpecifier(fromFile, toFile) {
 const RUNTIME_PLACEHOLDER = '__ATA_ERROR_RUNTIME__';
 const ERRORS_MODES = new Set(['auto', 'inline', 'shared']);
 
+// The registry without the definitions no module reaches. A shared
+// definitions file (Kubernetes ships one with hundreds) is mostly what a
+// given set of schemas never uses. Only `definitions` and `$defs` entries are
+// dropped, and only from a document every reference into which is a plain
+// pointer into them; a document reached as a whole, through an anchor, or
+// holding an embedded $id is kept as it is. The result is checked: every
+// root's references must still resolve against it, or the whole registry is
+// kept.
+function pruneRegistry(roots, byId) {
+  const used = new Map();
+  const keepWhole = new Set();
+  const seen = new Set();
+  const queue = [];
+  const hasInnerId = new Map();
+  const innerId = (doc) => {
+    let hit = hasInnerId.get(doc);
+    if (hit !== undefined) return hit;
+    hit = false;
+    const stack = [doc];
+    const visited = new Set();
+    while (stack.length && !hit) {
+      const n = stack.pop();
+      if (n === null || typeof n !== 'object' || visited.has(n)) continue;
+      visited.add(n);
+      if (n !== doc && !Array.isArray(n) && typeof n.$id === 'string') hit = true;
+      for (const k of Object.keys(n)) stack.push(n[k]);
+    }
+    hasInnerId.set(doc, hit);
+    return hit;
+  };
+  const docOf = new Map();
+  for (const [id, doc] of byId) docOf.set(id.replace(/#$/, ''), doc);
+  const reach = (doc, base, node) => {
+    if (node === null || typeof node !== 'object' || seen.has(node)) return;
+    seen.add(node);
+    queue.push([doc, base, node]);
+  };
+  const defsOf = (doc) => (doc.$defs && typeof doc.$defs === 'object' ? '$defs' : doc.definitions && typeof doc.definitions === 'object' ? 'definitions' : null);
+  for (const root of roots) reach(root, typeof root.$id === 'string' ? root.$id : null, root);
+  while (queue.length) {
+    const [doc, base, node] = queue.pop();
+    if (Array.isArray(node)) { for (const x of node) reach(doc, base, x); continue; }
+    for (const k of Object.keys(node)) {
+      const v = node[k];
+      if ((k === '$ref' || k === '$dynamicRef' || k === '$recursiveRef') && typeof v === 'string') {
+        let abs;
+        try { abs = base ? new URL(v, base).href : v.charCodeAt(0) === 35 ? null : new URL(v).href; } catch { abs = null; }
+        const local = v.charCodeAt(0) === 35;
+        const hash = abs === null ? -1 : abs.indexOf('#');
+        const uri = abs === null ? null : hash < 0 ? abs : abs.slice(0, hash);
+        const target = local ? doc : uri !== null ? docOf.get(uri) : undefined;
+        if (target === undefined) continue;
+        const frag = local ? v.slice(1) : hash < 0 ? '' : abs.slice(hash + 1);
+        const tbase = local ? base : uri;
+        const m = /^\/(\$defs|definitions)\/([^/]+)/.exec(frag);
+        const which = defsOf(target);
+        if (k !== '$ref' || m === null || m[1] !== which) {
+          keepWhole.add(target);
+          reach(target, tbase, target);
+          continue;
+        }
+        let name = m[2];
+        try { name = decodeURIComponent(name); } catch {}
+        name = name.replace(/~1/g, '/').replace(/~0/g, '~');
+        let set = used.get(target);
+        if (set === undefined) { set = new Set(); used.set(target, set); }
+        set.add(name);
+        // The rest of the document around its definitions is used too.
+        for (const key of Object.keys(target)) if (key !== which) reach(target, tbase, target[key]);
+        reach(target, tbase, target[which][name]);
+      } else if (v !== null && typeof v === 'object') {
+        reach(doc, base, v);
+      }
+    }
+  }
+  const out = new Map();
+  for (const [id, doc] of byId) {
+    const which = defsOf(doc);
+    if (which === null || keepWhole.has(doc) || innerId(doc) || roots.includes(doc)) { out.set(id, doc); continue; }
+    const names = used.get(doc) || new Set();
+    const defs = {};
+    for (const name of Object.keys(doc[which])) if (names.has(name)) Object.defineProperty(defs, name, { value: doc[which][name], enumerable: true, writable: true, configurable: true });
+    out.set(id, { ...doc, [which]: defs });
+  }
+  for (const root of roots) {
+    if (!aot._refsResolveWithin(root, out)) return byId;
+  }
+  // The registry documents' own references too, as the runtime may walk any
+  // part of a definition it keeps.
+  for (const doc of out.values()) if (!aot._refsResolveWithin(doc, out)) return byId;
+  return out;
+}
+
 async function build(opts) {
   const globs = opts.globs || [];
   if (globs.length === 0) throw new Error('build: at least one glob required');
@@ -138,6 +231,28 @@ async function build(opts) {
   const warnings = [];
   const entries = [];
 
+  // Schemas that reference each other: a schema whose references do not all
+  // land inside it gets the other inputs registered beside it, each under its
+  // $id, or, with `baseUri`, an input without one under the base URI and its
+  // file name. In schema mode its module then resolves against one registry
+  // module the build writes (registrySource); otherwise it is a
+  // self-contained module carrying what it references. A schema that
+  // resolves within itself is built exactly as it would be alone.
+  if (opts.baseUri !== undefined) {
+    try { new URL(opts.baseUri); } catch { throw new Error(`build: baseUri must be an absolute URI (got "${opts.baseUri}")`); }
+  }
+  let siblings = [];
+  for (const input of inputs) {
+    try {
+      const sch = parseSchemaFile(input);
+      if (sch === null || typeof sch !== 'object' || Array.isArray(sch)) continue;
+      if (typeof sch.$id === 'string' && sch.$id !== '') siblings.push({ input, schema: sch });
+      else if (opts.baseUri !== undefined) siblings.push({ input, schema: { $id: new URL(path.basename(input), opts.baseUri).href, ...sch } });
+    } catch {}
+  }
+  if (siblings.length === 0) siblings = null;
+  const REGISTRY_PLACEHOLDER = '__ATA_SCHEMA_REGISTRY__';
+
   const compileOne = (input, raw) => {
     const schema = parseSchemaFile(input);
     // The build is where an authoring mistake is cheapest to stop: a typo
@@ -151,7 +266,13 @@ async function build(opts) {
         return { error: problems.map((x) => `strict mode: ${x.message} at ${x.path}`).join('; ') };
       }
     }
-    const v = new Validator(schema);
+    const needs = siblings !== null && schema !== null && typeof schema === 'object' && !Array.isArray(schema) && !aot._refsResolveWithin(schema);
+    const self = needs ? siblings.find((x) => x.input === input) : undefined;
+    const others = needs ? siblings.filter((x) => x.input !== input && (self === undefined || x.schema.$id !== self.schema.$id)).map((x) => x.schema) : null;
+    // Known under the base URI too, so its own relative references resolve
+    // against it.
+    const own = self !== undefined ? self.schema : schema;
+    const v = others !== null && others.length > 0 ? new Validator(own, { schemas: others }) : new Validator(schema);
     let sourceMap = null;
     if (source) {
       // Only attempt position map for JSON (the scanner is JSON-only).
@@ -174,14 +295,37 @@ async function build(opts) {
       onWarning: (w, meta) => inputWarnings.push({ message: w, kind: (meta && meta.kind) || 'general' }),
     });
     const compact = schemaMode && src
-      ? aot.toSchemaModule(v, { format, runtime: RUNTIME_PLACEHOLDER })
+      ? aot.toSchemaModule(v, others !== null && others.length > 0 ? { format, runtime: RUNTIME_PLACEHOLDER, registry: REGISTRY_PLACEHOLDER } : { format, runtime: RUNTIME_PLACEHOLDER })
       : sharable && src ? aot.toCompactModule(v, { format, formatMode: opts.formatMode, errorRuntime: RUNTIME_PLACEHOLDER }) : null;
     // The runtime parts this module's schema needs (see runtimeFeatures).
-    const features = compact ? require('./error-runtime').runtimeFeatures([require('./schema-strip').stripAnnotations(v._schemaObj)]) : null;
+    // A registry module's schema reaches the others: what it needs from the
+    // registry, by $id, is every schema registered beside it. A key that is
+    // not its schema's $id cannot be found by the runtime, which keys the
+    // registry by $id: such a module is written self-contained.
+    let registryEntries = null;
+    let compactOut = compact;
+    if (compactOut && others !== null && others.length > 0) {
+      // A schema without an $id is not in the registry: its module carries it.
+      registryEntries = typeof v._schemaObj.$id === 'string' ? [v._schemaObj] : [];
+      for (const [id, sub] of v._schemaMap) {
+        if (!sub || typeof sub !== 'object' || sub.$id !== id) { compactOut = null; registryEntries = null; break; }
+        registryEntries.push(sub);
+      }
+    }
+    const { stripAnnotations: _strip } = require('./schema-strip');
+    const features = compactOut ? require('./error-runtime').runtimeFeatures((registryEntries || [v._schemaObj]).map(_strip)) : null;
     // A module that imports the pattern engine needs it in the runtime,
     // whatever the schema scan said.
-    if (features && compact.includes('_ataCompileSafe')) features['safe-regex'] = true;
-    return { schema, src, compact, features, inputWarnings };
+    if (features && compactOut.includes('_ataCompileSafe')) features['safe-regex'] = true;
+    // Why there is no module, when the reason is a reference: which one, and
+    // what would resolve it.
+    let unresolved = null;
+    if (!src) {
+      const miss = {};
+      const registry = v._schemaMap && v._schemaMap.size > 0 ? v._schemaMap : null;
+      if (!aot._refsResolveWithin(v._schemaObj, registry, miss) && typeof miss.ref === 'string') unresolved = miss.ref;
+    }
+    return { schema, src, compact: compactOut, features, registryEntries, root: v._schemaObj, usesSiblings: others !== null, unresolved, inputWarnings };
   };
 
   for (const input of inputs) {
@@ -196,6 +340,9 @@ async function build(opts) {
         cacheEntry.output === output &&
         !!cacheEntry.sharable === sharable &&
         !!cacheEntry.schemaMode === schemaMode &&
+        // A module built against the other inputs depends on them too, and
+        // the registry is put together from such modules: always rebuilt.
+        !cacheEntry.usesSiblings &&
         fs.existsSync(output) &&
         cacheEntry.outputHash === hashContent(fs.readFileSync(output))
       );
@@ -219,13 +366,15 @@ async function build(opts) {
         for (const x of r.inputWarnings) warnings.push({ input, warning: x.message, kind: x.kind });
       }
       if (!r.src) {
-        const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';
+        const reason = r.unresolved !== null
+          ? `$ref "${r.unresolved}" does not resolve: no input has that $id. Add the schema it names as an input${opts.baseUri === undefined ? ', and if that file has no $id, give it one with --base-uri' : ''}`
+          : 'schema is not AOT-compatible (toStandaloneModule returned null)';
         if (opts.strict) failed.push({ input, error: reason });
         else skipped.push({ input, reason });
         continue;
       }
       entries.push({
-        input, output, raw, inputHash, schema: r.schema, src: r.src, compact: r.compact, features: r.features,
+        input, output, raw, inputHash, schema: r.schema, src: r.src, compact: r.compact, features: r.features, registryEntries: r.registryEntries, root: r.root, usesSiblings: r.usesSiblings,
         fullGz: zlib.gzipSync(r.src).length,
         compactGz: r.compact ? zlib.gzipSync(r.compact).length : null,
       });
@@ -265,6 +414,19 @@ async function build(opts) {
   for (const e of entries) {
     e.mode = runtime !== null && candidates.includes(e) ? (schemaMode ? 'schema' : 'compact') : 'inline';
   }
+  // The registry the schema modules resolve against: every schema any of them
+  // needs, once, by $id.
+  let registryPath = null;
+  let registrySrc = null;
+  if (runtime !== null) {
+    const byId = new Map();
+    for (const e of entries) if (e.mode !== 'inline' && e.registryEntries) for (const sub of e.registryEntries) if (!byId.has(sub.$id)) byId.set(sub.$id, sub);
+    if (byId.size > 0) {
+      registryPath = path.join(path.dirname(runtime.path), 'ata-registry' + (format === 'cjs' ? '.cjs' : '.mjs'));
+      const roots = entries.filter((e) => e.mode !== 'inline' && e.registryEntries).map((e) => e.root);
+      registrySrc = aot.registrySource([...pruneRegistry(roots, byId).values()], format);
+    }
+  }
 
   for (const e of entries) {
     const { input, output } = e;
@@ -282,9 +444,10 @@ async function build(opts) {
         e.schema = r.schema; e.src = r.src; e.compact = r.compact; e.features = r.features;
         if (e.mode !== 'inline' && !r.compact) e.mode = 'inline';
       }
-      const src = e.mode !== 'inline'
+      let src = e.mode !== 'inline'
         ? e.compact.split(JSON.stringify(RUNTIME_PLACEHOLDER)).join(JSON.stringify(importSpecifier(output, runtime.path)))
         : e.src;
+      if (e.mode !== 'inline' && e.registryEntries) src = src.split(JSON.stringify(REGISTRY_PLACEHOLDER)).join(JSON.stringify(importSpecifier(output, registryPath)));
       fs.mkdirSync(path.dirname(output), { recursive: true });
       fs.writeFileSync(output, src);
       const outBytes = Buffer.byteLength(src, 'utf8');
@@ -321,6 +484,7 @@ async function build(opts) {
         fullGz: e.fullGz,
         compactGz: e.compactGz,
         features: e.features || undefined,
+        usesSiblings: e.usesSiblings || undefined,
       };
     } catch (err) {
       failed.push({ input, error: err.message });
@@ -335,11 +499,21 @@ async function build(opts) {
       fs.writeFileSync(runtime.path, runtime.src);
     }
     runtimeReport = { output: runtime.path, bytes: Buffer.byteLength(runtime.src, 'utf8'), gzipBytes: runtime.gz };
+    if (registrySrc !== null) {
+      const cur = fs.existsSync(registryPath) ? fs.readFileSync(registryPath, 'utf8') : null;
+      if (cur !== registrySrc) fs.writeFileSync(registryPath, registrySrc);
+      runtimeReport.registry = { output: registryPath, bytes: Buffer.byteLength(registrySrc, 'utf8'), gzipBytes: zlib.gzipSync(registrySrc).length };
+    }
   }
 
   writeCache(opts.cacheFile, newCache);
 
-  return { compiled, cached, skipped, failed, warnings, runtime: runtimeReport };
+  // The self-contained source is built for every input, so its error-detail
+  // decline is recorded even where the module written is a compact or schema
+  // module, whose errors come from the runtime. Only the written one counts.
+  const fromRuntime = new Set(entries.filter((e) => e.mode !== 'inline').map((e) => e.input));
+  const kept = warnings.filter((w) => !(w.kind === 'error-detail' && fromRuntime.has(w.input)));
+  return { compiled, cached, skipped, failed, warnings: kept, runtime: runtimeReport };
 }
 
 async function watch(opts, onReport) {

package/lib/aot-impl.js

@@ -687,13 +687,14 @@ function hasRefKey(n, seen) {
   return false;
 }
 
-function refsResolveWithin(schema) {
+// miss: an object that gets `ref`, the first reference that does not resolve.
+function refsResolveWithin(schema, registry, miss) {
   // No reference anywhere (a key of that name inside a value counts too):
   // nothing to resolve, and no index to build.
-  if (!hasRefKey(schema, new Set())) return true;
+  if (!registry && !hasRefKey(schema, new Set())) return true;
   const { indexSchemas, resolveRef } = require('./interpreter-core')._refInternals;
   let state;
-  try { state = indexSchemas(schema, null); } catch { return false; }
+  try { state = indexSchemas(schema, registry || null); } catch { return false; }
   for (const [node, base] of state.nodeBase) {
     if (node === null || typeof node !== 'object') continue;
     for (const k of ['$ref', '$dynamicRef']) {
@@ -701,15 +702,19 @@ function refsResolveWithin(schema) {
       if (r === undefined) continue;
       if (typeof r !== 'string') return false;
       let hit;
-      try { hit = resolveRef(r, base, state); } catch { return false; }
-      if (hit.node === undefined) return false;
+      try { hit = resolveRef(r, base, state); } catch { if (miss) miss.ref = r; return false; }
+      if (hit.node === undefined) { if (miss) miss.ref = r; return false; }
     }
   }
   return true;
 }
 
 const COMPACT_OPTIONS = new Set(['engine', 'strictSchema', 'logger', 'source']);
-function compactDecline(validator) {
+// registryMode: for a schema module that resolves its references against the
+// build's registry (toSchemaModule with `registry`): schemas registered beside
+// the root are allowed, and every reference has to land in the schema or in
+// one of them.
+function compactDecline(validator, registryMode) {
   // Options are allowed by name, not refused by name: one this list does not
   // know (assertFormat: false, baseURI, a future one) may change what the
   // verdict means, and the runtime would not know to follow it.
@@ -718,19 +723,24 @@ function compactDecline(validator) {
   validator._ensureCompiled();
   const o = validator._options || {};
   for (const k of Object.keys(o)) {
-    if (o[k] === undefined || COMPACT_OPTIONS.has(k)) continue;
+    if (o[k] === undefined || COMPACT_OPTIONS.has(k) || (registryMode === true && k === 'schemas')) continue;
     return 'option ' + k;
   }
   if (validator._usesKeywords || validator._externalChecks) return 'custom keywords';
   if (validator._userFormats && Object.keys(validator._userFormats).length) return 'custom formats';
-  if (validator._schemaMap && validator._schemaMap.size > 0) return 'schemas registered beside the root';
+  if (registryMode !== true && validator._schemaMap && validator._schemaMap.size > 0) return 'schemas registered beside the root';
   if (validator._schemaObj === null || typeof validator._schemaObj !== 'object') return 'boolean schema';
   // The runtime has the embedded schema and nothing else: a reference that
   // lands outside it (a meta-schema the runtime Validator resolves from its
   // vendored copies, a schema registered later) would come back unresolved,
   // and the errors with it. The check runs on the schema as embedded.
   const { stripAnnotations } = require('./schema-strip');
-  if (!refsResolveWithin(stripAnnotations(validator._schemaObj))) return 'a reference outside the schema';
+  let registry = null;
+  if (registryMode === true && validator._schemaMap && validator._schemaMap.size > 0) {
+    registry = new Map();
+    for (const [id, sub] of validator._schemaMap) registry.set(id, stripAnnotations(sub));
+  }
+  if (!refsResolveWithin(stripAnnotations(validator._schemaObj), registry)) return registry ? 'a reference outside the schema and the registry' : 'a reference outside the schema';
   return null;
 }
 
@@ -755,7 +765,12 @@ function toCompactModule(validator, opts) {
 function toSchemaModule(validator, opts) {
   assertEmittable(validator, 'toSchemaModule');
   if (!opts || typeof opts.runtime !== 'string') throw new TypeError('toSchemaModule: opts.runtime (the import specifier of the schema runtime) is required');
-  if (compactDecline(validator) !== null) return null;
+  // opts.registry: the import specifier of the build's registry module (the
+  // array of schemas, written by errorRegistrySource), for schemas that
+  // reference each other by $id. The module then names its schema by $id and
+  // carries no copy of it.
+  const registry = typeof opts.registry === 'string' ? opts.registry : null;
+  if (compactDecline(validator, registry !== null) !== null) return null;
   const format = opts.format || 'esm';
   const { stripAnnotations } = require('./schema-strip');
   const { isV1Dialect } = require('./dialect');
@@ -770,12 +785,15 @@ function toSchemaModule(validator, opts) {
     if ('$anchor' in n || '$dynamicAnchor' in n || (!root && '$id' in n)) return false;
     return Object.keys(n).every((k) => flatWalk(n[k], false));
   };
-  const rtOpts = [isV1Dialect(sch) ? 'v1: true' : '', flatWalk(stripped, true) ? 'flat: true' : ''].filter(Boolean).join(', ');
+  const ownId = registry !== null && typeof sch.$id === 'string' ? sch.$id : null;
+  const rtOpts = [isV1Dialect(sch) ? 'v1: true' : '', registry === null && flatWalk(stripped, true) ? 'flat: true' : '', registry !== null ? 'registry: _ataRegistry' : '', ownId !== null ? 'id: ' + JSON.stringify(ownId) : ''].filter(Boolean).join(', ');
   const hashSrc = hashOf(validator);
   const spec = JSON.stringify(opts.runtime);
-  const imp = format === 'esm'
+  const regSpec = registry !== null ? JSON.stringify(registry) : null;
+  const imp = (format === 'esm'
     ? `import { createValidator as _ataCreateValidator } from ${spec};\n`
-    : `const { createValidator: _ataCreateValidator } = require(${spec});\n`;
+    : `const { createValidator: _ataCreateValidator } = require(${spec});\n`)
+    + (regSpec === null ? '' : format === 'esm' ? `import _ataRegistry from ${regSpec};\n` : `const _ataRegistry = require(${regSpec});\n`);
   const exp = format === 'esm'
     ? 'export { validate, isValid, schemaHash, ataVersion };\nexport default { validate, isValid, schemaHash, ataVersion };\n'
     : 'module.exports = { validate, isValid, schemaHash, ataVersion };\nmodule.exports.default = module.exports;\n';
@@ -786,7 +804,7 @@ function toSchemaModule(validator, opts) {
 ${imp}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const ABORT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ code: 'ATA9000', message: 'validation failed', keyword: '__abort_early__', path: '' })]) });
 let _ataV = null;
-function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(JSON.parse(${text})${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
+function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(${ownId !== null ? 'null' : 'JSON.parse(' + text + ')'}${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
 function isValid(data) { return _ataGet().isValid(data); }
 function validate(data) { const v = _ataGet(); if (v.isValid(data)) return VALID; const e = v.errors(data); return e === null ? ABORT : { valid: false, errors: e }; }
 const schemaHash = ${JSON.stringify(hashSrc)};
@@ -794,6 +812,18 @@ const ataVersion = ${JSON.stringify(ATA_VERSION)};
 ${exp}`;
 }
 
+// The registry module schema modules import when their schemas reference each
+// other: every schema of the build, without its descriptive keywords, as one
+// array the runtime turns into its id-to-schema table.
+function registrySource(schemas, format) {
+  const { stripAnnotations } = require('./schema-strip');
+  const text = JSON.stringify(JSON.stringify(schemas.map((x) => stripAnnotations(x && x._schemaObj !== undefined ? x._schemaObj : x)))).replace(/</g, '\\u003c');
+  const head = `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.\n// The schemas of one build, which its schema modules resolve references against.\n'use strict';\n`;
+  return format === 'cjs'
+    ? head + `module.exports = JSON.parse(${text});\n`
+    : head + `export default JSON.parse(${text});\n`;
+}
+
 // Bundle multiple validators into a single JS file for fast startup.
 // Usage:
 //   const bundle = Validator.bundle([schema1, schema2, ...]);
@@ -1110,6 +1140,7 @@ module.exports = {
   toStandaloneModule: htmlSafeResult(toStandaloneModule),
   toCompactModule: htmlSafeResult(toCompactModule),
   toSchemaModule: htmlSafeResult(toSchemaModule),
+  registrySource: htmlSafeResult(registrySource),
   compactDecline,
   // `schemas`: the validators (or schemas) whose compact modules will import
   // this runtime; parts none of them needs are left out. Omitted, the
@@ -1130,3 +1161,5 @@ module.exports = {
   bundleCompact: htmlSafeResult(bundleCompact),
   loadBundle,
 };
+// For the build only (lib/aot-build.js), not part of ata-validator/aot.
+Object.defineProperty(module.exports, '_refsResolveWithin', { value: refsResolveWithin, enumerable: false });

package/lib/schema-order.js

@@ -57,17 +57,53 @@ function rankFor(rootSchema, schemaPath) {
   return rank;
 }
 
+// The documents a root's references reach beyond itself, id to schema, from
+// the validators that own the root (the `schemas` option, addSchema) or a
+// schema module's registry. Several validators of one root schema register
+// their maps into one; an id that two of them give different schemas makes the
+// root resolve nothing outside itself, as it did before any was registered.
+const _documents = new WeakMap();
+const CONFLICT = new Map();
+function registerDocuments(rootSchema, map) {
+  if (rootSchema === null || typeof rootSchema !== 'object' || !map || map.size === 0) return;
+  const had = _documents.get(rootSchema);
+  if (had === CONFLICT) return;
+  if (had === undefined) { _documents.set(rootSchema, new Map(map)); _rankCache.delete(rootSchema); return; }
+  let added = false;
+  for (const [id, doc] of map) {
+    const cur = had.get(id);
+    if (cur === undefined) { had.set(id, doc); added = true; } else if (cur !== doc) { _documents.set(rootSchema, CONFLICT); _rankCache.delete(rootSchema); return; }
+  }
+  if (added) _rankCache.delete(rootSchema);
+}
+
+function withoutEmptyFragment(uri) {
+  return uri.endsWith('#') ? uri.slice(0, -1) : uri;
+}
+
+function resolveUri(ref, base) {
+  try { return base ? new URL(ref, base).href : new URL(ref).href; } catch { return null; }
+}
+
 function computeRank(rootSchema, schemaPath) {
   const rank = [];
   let node = rootSchema;
   let start = 1;
   let hops = 0;
+  const docs = _documents.get(rootSchema);
+  // The document the walk is in and the base URI references resolve against,
+  // for following a reference into another document.
+  let doc = rootSchema;
+  // A root without an $id can still name another document by absolute URI.
+  const follow = docs !== undefined && docs !== CONFLICT;
+  let base = follow && typeof rootSchema.$id === 'string' ? resolveUri(rootSchema.$id, null) : null;
   while (start <= schemaPath.length) {
     let end = schemaPath.indexOf('/', start);
     if (end < 0) end = schemaPath.length;
     if (end === start) { start = end + 1; continue; }
     const seg = unescapePointerSegment(schemaPath.slice(start, end));
     if (node == null || typeof node !== 'object') break;
+    if (follow && node !== doc && !Array.isArray(node) && typeof node.$id === 'string' && node.$id[0] !== '#') base = resolveUri(node.$id, base);
     if (Array.isArray(node)) {
       const idx = Number(seg);
       if (!Number.isInteger(idx) || idx < 0 || idx >= node.length) break;
@@ -80,7 +116,11 @@ function computeRank(rootSchema, schemaPath) {
         // naming it. Ranking the rest inside the target, as if the target sat
         // under the `$ref` key, orders errors behind a reference by the
         // target's declaration order, as they are ordered inline.
-        const target = hops < 64 ? localTarget(rootSchema, node) : null;
+        let target = hops < 64 ? localTarget(doc, node) : null;
+        if (target === null && hops < 64 && follow) {
+          const remote = remoteTarget(docs, base, node);
+          if (remote !== null) { target = remote.node; doc = remote.doc; base = remote.base; }
+        }
         if (target === null) break;
         hops++;
         rank.push(keyIndex(node, '$ref'));
@@ -95,6 +135,28 @@ function computeRank(rootSchema, schemaPath) {
   return rank;
 }
 
+// The schema a node's `$ref` names in a registered document: { node, doc,
+// base }, or null when it names none (an anchor, an unknown document).
+function remoteTarget(docs, base, node) {
+  const ref = node.$ref;
+  if (typeof ref !== 'string' || ref.charCodeAt(0) === 35) return null;
+  const abs = resolveUri(ref, base);
+  if (abs === null) return null;
+  const hash = abs.indexOf('#');
+  const uri = hash < 0 ? abs : abs.slice(0, hash);
+  let target = docs.get(uri);
+  if (target === undefined) target = docs.get(uri + '#');
+  if (target === undefined) {
+    for (const [id, s] of docs) if (withoutEmptyFragment(resolveUri(id, null) || '') === uri) { target = s; break; }
+  }
+  if (target === null || typeof target !== 'object') return null;
+  const frag = hash < 0 ? '' : abs.slice(hash + 1);
+  if (frag === '') return { node: target, doc: target, base: uri };
+  if (frag.charCodeAt(0) !== 47) return null;
+  const t = localTarget(target, { $ref: '#' + frag });
+  return t === null ? null : { node: t, doc: target, base: uri };
+}
+
 // The schema a node's `$ref` names, when it is a pointer into this document.
 function localTarget(rootSchema, node) {
   const ref = node.$ref;
@@ -191,4 +253,4 @@ function ordinalFor(rootSchema, schemaPath) {
 const _missCache = new WeakMap();
 const MISS_CACHE_LIMIT = 4096;
 
-module.exports = { rankFor, ordinalFor, unescapePointerSegment };
+module.exports = { rankFor, ordinalFor, unescapePointerSegment, registerDocuments };

package/lib/schema-runtime-entry.js

@@ -10,8 +10,32 @@
 const { createInterpreter } = require('./interpreter');
 const { errorsOf, interpreterOptions } = require('./error-runtime-entry');
 
+// A registry is the array of schemas a build writes beside schema modules
+// whose schemas reference each other by `$id` (ata-registry.mjs). It becomes
+// one Map, id to schema, shared by every module of the build.
+const _maps = new WeakMap();
+function registryMap(registry) {
+  let map = _maps.get(registry);
+  if (map === undefined) {
+    map = new Map();
+    for (const s of registry) map.set(s.$id, s);
+    _maps.set(registry, map);
+  }
+  return map;
+}
+
+// options.registry and options.id: the module's schema is the registry entry
+// with that `$id`, and its references resolve against the registry.
 function createValidator(schema, codeOf, options) {
-  const interp = createInterpreter(schema, interpreterOptions(options));
+  const opts = interpreterOptions(options);
+  if (options && options.registry) {
+    const map = registryMap(options.registry);
+    if (schema === null || schema === undefined) schema = map.get(options.id);
+    opts.schemaMap = map;
+    opts.flat = false;
+    require('./schema-order').registerDocuments(schema, map);
+  }
+  const interp = createInterpreter(schema, opts);
   return {
     isValid: (data) => interp.isValid(data),
     errors: (data) => errorsOf(interp, schema, codeOf, data),

package/lib/validator-core.js

@@ -864,6 +864,9 @@ class Validator {
     if (this._initialized) return;
     this._ensureVocabularies();
     this._initialized = true;
+    // Errors behind a reference into a registered document are ordered as
+    // they would be inline: the ordering follows the reference there.
+    if (this._schemaMap && this._schemaMap.size > 0) require('./schema-order').registerDocuments(this._schemaObj, this._schemaMap);
 
     const schemaObj = this._schemaObj;
     const options = this._options;

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -172,13 +172,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.50.0",
-    "@ata-validator/native-darwin-x64": "1.50.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.50.0",
-    "@ata-validator/native-linux-arm64-musl": "1.50.0",
-    "@ata-validator/native-linux-x64-gnu": "1.50.0",
-    "@ata-validator/native-linux-x64-musl": "1.50.0",
-    "@ata-validator/native-win32-x64": "1.50.0"
+    "@ata-validator/native-darwin-arm64": "1.51.0",
+    "@ata-validator/native-darwin-x64": "1.51.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.51.0",
+    "@ata-validator/native-linux-arm64-musl": "1.51.0",
+    "@ata-validator/native-linux-x64-gnu": "1.51.0",
+    "@ata-validator/native-linux-x64-musl": "1.51.0",
+    "@ata-validator/native-win32-x64": "1.51.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"