ata-validator 1.52.0 → 1.54.0

package/README.md

@@ -298,6 +298,13 @@ for.
 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.
 
+**On Node 22 or later, a process that starts often can keep V8's compiled code between
+starts.** Point `NODE_COMPILE_CACHE` at a directory that survives the restart, or call
+`module.enableCompileCache()` in your entry. Measured on an Apple M4 Pro, Node 25.2.1:
+loading ata goes from 4.9 to 2.7 ms, and a fresh process reaches its first validated
+document in 5.3 ms instead of 7.8. This is Node's feature, it covers every module the
+process loads, and ata does not turn it on for you.
+
 **In a browser, on an edge runtime, or anywhere cold starts are charged, compile.** This
 is where the difference is the whole story, and it is also where `new Function` is often
 blocked outright, which the compiled module does not need. With a bundler, adding `@ata-project/unplugin`

package/compat.js

@@ -21,12 +21,30 @@ const { resolvePointer } = require('./lib/pointer.js');
 // `strictTuples` and `strictRequired` are accepted and ignored.
 
 const { Validator } = require('./index');
+// The interpreted engine's coercion where each type is checked and its
+// discriminator, which only compat asks for (see lib/interpreter-compat.js).
+require('./lib/interpreter-core')._setCompat(require('./lib/interpreter-compat'));
 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 +76,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 +110,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 +129,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 +141,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 +266,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 +288,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 +338,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 +374,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 +452,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 +478,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 +503,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 +521,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 +563,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 +577,129 @@ 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_REF = 1 << 16, F_BEYOND = 1 << 17, F_DISCR = 1 << 18, F_DEFAULT = 1 << 19, F_ALLOF = 1 << 20, F_FORMAT = 1 << 21;
+_scan._setExtraKeys(new Map([
+  ['$ref', F_REF | F_BEYOND], ['$dynamicRef', F_BEYOND], ['allOf', F_ALLOF | F_BEYOND],
+  ['anyOf', F_BEYOND], ['oneOf', F_BEYOND], ['not', F_BEYOND], ['if', F_BEYOND],
+  ['then', F_BEYOND], ['else', F_BEYOND], ['additionalProperties', F_BEYOND],
+  ['patternProperties', F_BEYOND], ['prefixItems', F_BEYOND], ['additionalItems', F_BEYOND],
+  ['contains', F_BEYOND], ['dependentSchemas', F_BEYOND], ['dependencies', F_BEYOND],
+  ['propertyNames', F_BEYOND], ['unevaluatedProperties', F_BEYOND], ['unevaluatedItems', F_BEYOND],
+  ['discriminator', F_DISCR], ['default', F_DEFAULT], ['format', F_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/lib/codegen-engine.js

@@ -69,7 +69,8 @@ function richBuilder(combRich, root, presentFallback, fallback, plain, cleanPlai
   return (data) => {
     const r = combRich(data);
     if (r.valid || !r.errors || !r.errors.length) return presentFallback(fallback, data);
-    const out = _needsOrdering(r.errors) ? _sortErrors(root, r.errors) : r.errors;
+    // `mo`: the list came out in the reader's order (see compileToJSCombined).
+    const out = r.mo === true || !_needsOrdering(r.errors) ? r.errors : _sortErrors(root, r.errors);
     // A collapsed oneOf or anyOf comes out plain (no docUrl) and is enriched
     // here, its branch errors with it, as presentErrors would.
     for (let i = 0; i < out.length; i++) {