ata-validator 1.47.0 → 1.49.0

package/README.md

@@ -43,6 +43,16 @@ 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, 1301 of 1301 Draft 2020-12 cases. The buffer and parallel APIs (`isValid` on raw buffers, `isValidPrepadded`, `isValidNDJSON`, `isValidParallel`, `countValid`, `batchIsValid`, `validateAndParse`) work without the addon too, answering through the same checks as `isValidJSON()`, slower than the addon: 177 ns against 92 for a small document on Node 25. In a browser, which has no `Buffer`, they throw and name the methods to use instead.
 
+Where the size of what ships matters more than nanoseconds per call, `ata-validator/lite` is
+the same `Validator` on the interpreted engine alone, without the code generator: the same
+verdicts and errors, 58 KB gzipped in a bundled worker against 136 KB for the full entry.
+It leaves out what needs the generator, `parse()` and the ahead-of-time bundle methods.
+
+On Deno the same package is `npm:ata-validator` or `jsr:@ata/validator`; the JSR package
+re-exports the npm one at the same version, and CI runs the official suite under Deno. The
+details, and what Deno Deploy's refusal of dynamic code means for it, are in
+[docs/edge-runtimes.md](docs/edge-runtimes.md).
+
 Those four now agree with `validate()` on every case of the official suite, 3365 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 1301 of 1301 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
@@ -99,6 +109,29 @@ file.
   passes with nothing failed, errored or skipped under Bowtie's own runner. The v1 dialect is
   declared in a pending harness change that waits for a Bowtie release.
 
+### Side by side
+
+[validator-benchmarks](https://github.com/ata-core/validator-benchmarks) is ata's own
+comparison, so it comes after the ones above: eleven validators on three realistic bodies
+and four scenes, each library in its own process, 27 samples per cell, every schema and
+document in the repository. On an order body with formats and a pattern, 900 valid
+documents, Node 24:
+
+[![Documents a second on one order body, eleven validators](https://raw.githubusercontent.com/ata-core/validator-benchmarks/main/media/race-order-verdict-valid.gif)](https://github.com/ata-core/validator-benchmarks/blob/main/media/race-order-verdict-valid.mp4)
+
+| | documents a second, the verdict | same, `new Function` refused |
+|---|---:|---:|
+| ata | 3,295,880 | 607,614 |
+| ata, compiled module | 3,319,594 | 3,344,948 |
+| typebox | 1,638,813 | EvalError |
+| ajv | 1,285,492 | EvalError |
+| typia | 939,572 | 964,507 |
+| zod | 440,473 | 237,176 |
+
+Where ata is behind is in the same tables: on a four-field body that fails, ajv answers the
+verdict faster, and with every error read it does 6.6M a second against ata's 2.9M with rich
+errors (7.6M with `richErrors: false`).
+
 ## Why AOT
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
@@ -244,13 +277,13 @@ is the most common way to get a misleading number out of this library.
 
 | | compiled with `ata build` | runtime `new Validator(schema)` |
 |---|---|---|
-| In a bundle, gzipped | **2.1 KB** | 125.0 KB |
+| In a bundle, gzipped | **2.1 KB** | 126.1 KB |
 | Time to a served request | **3.5 ms** | 7.6 ms |
 | Schema known when | build time | any time |
 
 The bundle row is the ten-field user schema in
 `tests/fixtures/error-dx/user.schema.json`, every export of the compiled module against
-`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.47.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.48.0.
 The startup row is a Hono route on Bun 1.4, the median of three rounds of best-of-seven, from
 `benchmark/bundle`, against 3.5 ms for the same app doing no validation at all, so the
 compiled path costs nothing measurable to start. The runtime figure is what it is because
@@ -280,6 +313,15 @@ const result = v.validate(data)
 
 The runtime API is unchanged from previous releases. Code written against the default validator's class keeps working through `ata-validator/compat`, which covers `compile`, `addSchema`, `addFormat`, `addKeyword`, `errorsText` and the rest of that surface, and reports errors in the same shape and order. `npx ata migrate` reports what the switch would change in a project, and what it cannot translate, before anything is written. See [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
 
+Coming from the default validator, one command reports what the switch touches and a second applies the mechanical part:
+
+```bash
+npx ata migrate            # per file: imports to rewrite, addFormats() calls that go, sites to look at by hand
+npx ata migrate --write    # rewrites the imports to ata-validator/compat and removes the calls, leaves the rest
+```
+
+Coercion, defaults, `allErrors` and the error objects behave as before; the details and the limits are in [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
+
 ## Usage
 
 ### Node.js
@@ -684,7 +726,7 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 
 ### Dialects
 
-`$schema` selects the dialect. Draft 2020-12 is the default, draft-07 is normalized on the way in, and `https://json-schema.org/v1` (or the dated `https://json-schema.org/v1/2026`) selects JSON Schema v1.
+`$schema` selects the dialect. Draft 2020-12 is the default; draft-07, draft-06 and Draft 2019-09 are rewritten to the 2020-12 spelling on the way in (draft-06 as draft-07 without `if`/`then`/`else`, 2019-09's tuple `items` and `$recursiveRef` as `prefixItems` and `$dynamicRef`); and `https://json-schema.org/v1` (or the dated `https://json-schema.org/v1/2026`) selects JSON Schema v1. The official suite passes in full on all five: 1301 of 1301 on 2020-12, 1261 of 1261 on 2019-09, 929 of 929 on draft-07, 841 of 841 on draft-06 and 1135 of 1135 on v1, with code generation allowed and blocked. Draft-04 and earlier are not supported; draft-04's boolean `exclusiveMinimum`/`exclusiveMaximum` is read wherever it appears.
 
 Two things differ under v1. `propertyDependencies` selects a subschema by the value of a property rather than by its presence, which is what `dependentSchemas` does. And `$dynamicRef` no longer requires bookending: the reference resolves through the dynamic scope whether or not the schema it first lands on carries a matching `$dynamicAnchor`, so the outermost matching anchor still in scope wins. Everything else ata implements is identical under both dialects, so a schema that declares no `$schema` behaves exactly as before.
 

package/index.js

@@ -814,22 +814,40 @@ function hasDefaultsInside(node, seen) {
 function emitDefaults(node, ov, lines, st) {
   if (st.seen.has(node)) { st.cycle = true; return; }
   st.seen.add(node);
+  // A default is written only where the key is not an own property, and the
+  // own-property test used to be Object.hasOwn for every default on every
+  // call: on a configuration schema of 82 defaults that was 820 ns a call
+  // for a document that already carried every key, against 12 ns with the
+  // pass off. For a plain object (prototype Object.prototype) a key the
+  // prototype does not have is own exactly when reading it gives a value, so
+  // the read, an inline-cached load, settles the common case and hasOwn is
+  // consulted only when the read gives undefined. Keys Object.prototype does
+  // have (constructor, toString, __proto__) keep the hasOwn test, since the
+  // read would find the inherited one; so does any object with another
+  // prototype, where a read may find an inherited value of the same name.
+  const pk = '_pk' + st.n++;
+  lines.push(`const ${pk}=Object.getPrototypeOf(${ov})===Object.prototype`);
   for (const [key, prop] of Object.entries(node.properties || {})) {
     if (!prop || typeof prop !== 'object') continue;
     const k = JSON.stringify(key);
+    const inherited = key in Object.prototype;
+    const absent = inherited ? `!Object.hasOwn(${ov},${k})` : `(${ov}[${k}]===undefined||!${pk})&&!Object.hasOwn(${ov},${k})`;
     if (prop.default !== undefined) {
       const def = JSON.stringify(prop.default);
       // Assignment to a key named __proto__ hits the prototype setter
       // instead of creating a property; defineProperty writes an own key.
       lines.push(key === '__proto__'
-        ? `if(!Object.hasOwn(${ov},${k}))Object.defineProperty(${ov},${k},{value:${def},writable:true,enumerable:true,configurable:true})`
-        : `if(!Object.hasOwn(${ov},${k}))${ov}[${k}]=${def}`);
+        ? `if(${absent})Object.defineProperty(${ov},${k},{value:${def},writable:true,enumerable:true,configurable:true})`
+        : `if(${absent})${ov}[${k}]=${def}`);
     }
     // Into an own property that holds an object, arrays included, as the
-    // closure pass walks it.
+    // closure pass walks it. Object.prototype's own properties are functions
+    // apart from the __proto__ accessor, so on a plain object a read that
+    // gives an object is an own property for every other key.
     if (prop.properties && hasDefaultsInside(prop, new Set())) {
       const n = '_d' + st.n++;
-      lines.push(`if(Object.hasOwn(${ov},${k})){const ${n}=${ov}[${k}];if(typeof ${n}==='object'&&${n}!==null){`);
+      const own = inherited ? `Object.hasOwn(${ov},${k})` : `(${pk}||Object.hasOwn(${ov},${k}))`;
+      lines.push(`{const ${n}=${ov}[${k}];if(typeof ${n}==='object'&&${n}!==null&&${own}){`);
       emitDefaults(prop, n, lines, st);
       lines.push('}}');
     }

package/lib/aot-impl.js

@@ -113,6 +113,9 @@ function toStandalone(validator) {
   // Also capture error function source for zero-compile standalone load
   const jsErrFn = compileToJSCodegenWithErrors(
     typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
+    null,
+    null,
+    { noOrdinal: true },
   );
   const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
 
@@ -388,11 +391,14 @@ function toStandaloneModule(validator, opts) {
       `const _ER = function(e) { _ataStamp(e); this.valid = false; this.errors = e; };\n` +
       `${codeTableSource(onePass.keywords, onePass.formats)}const _vC = (function() {\n${onePass.core}\n})();\n`;
   } else if (!abortEarly) {
+    // A module returns the collector's errors as they are and never sorts
+    // them, so the ordinal the runtime sorts by (`_o`) has no reader there;
+    // it leaked into every error object a module reported.
     jsErrFn = compileToJSCodegenWithErrors(
       typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
       null,
       validator._userFormats,
-      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames } : null,
+      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames, noOrdinal: true } : { noOrdinal: true },
     );
     const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
     if (errSrc && jsErrFn._errFactory) {
@@ -665,6 +671,7 @@ function bundleStandalone(Validator, schemas, opts) {
       v._schemaObj,
       v._schemaMap,
       v._userFormats,
+      { noOrdinal: true },
     );
     if (jsFn._usesSafeRe || (jsErrFn && jsErrFn._usesSafeRe)) bundleUsesSafeRe = true;
     return { v, jsFn, jsErrFn };
@@ -757,6 +764,7 @@ function bundleCompact(Validator, schemas, opts) {
       v._schemaObj,
       v._schemaMap,
       v._userFormats,
+      { noOrdinal: true },
     );
     if (jsFn._usesSafeRe || (jsErrFn && jsErrFn._usesSafeRe)) bundleUsesSafeRe = true;
     // Hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) must travel with the

package/lib/draft7.js

@@ -1,19 +1,36 @@
 'use strict'
 
+// draft-06 is read through the same rules: it differs from draft-07 only in
+// lacking `if`/`then`/`else` (and the content and readOnly annotations), so a
+// draft-06 schema is a draft-07 schema with those three keywords inert. Before
+// this, a draft-06 schema was read under 2020-12 and its tuple `items`,
+// `additionalItems` and `dependencies` were not applied: 30 cases of the
+// official draft-06 suite accepted documents they must reject.
 const DRAFT7_SCHEMAS = new Set([
   'http://json-schema.org/draft-07/schema#',
   'http://json-schema.org/draft-07/schema',
+  'http://json-schema.org/draft-06/schema#',
+  'http://json-schema.org/draft-06/schema',
+])
+const DRAFT6_SCHEMAS = new Set([
+  'http://json-schema.org/draft-06/schema#',
+  'http://json-schema.org/draft-06/schema',
 ])
 
 function isDraft7(schema) {
-  return !!(schema && schema.$schema && DRAFT7_SCHEMAS.has(schema.$schema))
+  return !!(schema && typeof schema.$schema === 'string' && DRAFT7_SCHEMAS.has(schema.$schema))
+}
+
+function isDraft6(schema) {
+  return !!(schema && typeof schema.$schema === 'string' && DRAFT6_SCHEMAS.has(schema.$schema))
 }
 
 // `force` applies the draft-07 rules to a document that declares no dialect
 // of its own, which is how a retrieved schema inherits the root's draft.
-function normalizeDraft7(schema, force) {
+// `draft6` says the document, or the root it inherits from, is draft-06.
+function normalizeDraft7(schema, force, draft6) {
   if (!force && !isDraft7(schema)) return schema
-  _normalize(schema)
+  _normalize(schema, draft6 === true || isDraft6(schema))
   return schema
 }
 
@@ -21,9 +38,13 @@ function normalizeDraft7(schema, force) {
 // definitions are addressable by pointer, annotations are inert.
 const REF_SIBLINGS_KEPT = new Set(['$ref', '$defs', 'definitions', '$schema', '$comment', 'title', 'description', 'examples', 'default', 'readOnly', 'writeOnly'])
 
-function _normalize(schema) {
+function _normalize(schema, d6) {
   if (typeof schema !== 'object' || schema === null) return
 
+  // draft-06 has no conditional: `if`, `then` and `else` are unknown keywords
+  // there, so they are dropped rather than applied.
+  if (d6) { delete schema.if; delete schema.then; delete schema.else }
+
   // In draft-07 an object with `$ref` is that reference and nothing else:
   // sibling keywords, `$id` included, are ignored. Dropping them here gives
   // every engine the same reading without each having to know the draft.
@@ -74,7 +95,7 @@ function _normalize(schema) {
   for (const key of objSubs) {
     if (schema[key] && typeof schema[key] === 'object') {
       for (const v of Object.values(schema[key])) {
-        if (typeof v === 'object' && v !== null) _normalize(v)
+        if (typeof v === 'object' && v !== null) _normalize(v, d6)
       }
     }
   }
@@ -84,7 +105,7 @@ function _normalize(schema) {
   for (const key of arrSubs) {
     if (Array.isArray(schema[key])) {
       for (const s of schema[key]) {
-        if (typeof s === 'object' && s !== null) _normalize(s)
+        if (typeof s === 'object' && s !== null) _normalize(s, d6)
       }
     }
   }
@@ -94,7 +115,7 @@ function _normalize(schema) {
                        'additionalProperties', 'propertyNames']
   for (const key of singleSubs) {
     if (typeof schema[key] === 'object' && schema[key] !== null) {
-      _normalize(schema[key])
+      _normalize(schema[key], d6)
     }
   }
 }
@@ -248,4 +269,81 @@ function _stripFormat(schema, seen) {
   }
 }
 
-module.exports = { isDraft7, normalizeDraft7, normalizeNullable, normalizeExclusiveBounds, stripFormatAssertions }
+// Draft 2019-09 differs from 2020-12, which every engine here reads, in two
+// places: the array form of `items` with `additionalItems` (2020-12 spells
+// them `prefixItems` and `items`), and `$recursiveRef`/`$recursiveAnchor`,
+// which 2020-12 generalised into `$dynamicRef`/`$dynamicAnchor`. Both are
+// rewritten to the 2020-12 spelling. Before, a 2019-09 schema was read as
+// 2020-12 as written, and 38 cases of the official 2019-09 suite accepted
+// documents they must reject.
+//
+// The recursive pair maps one to one: a resource whose root says
+// `$recursiveAnchor: true` gets a `$dynamicAnchor` of a reserved name, and
+// `$recursiveRef: "#"` becomes a `$dynamicRef` to that name when its resource
+// carries the anchor, and a plain `$ref: "#"` when it does not, which is what
+// 2019-09 says it means then. The outward search for the outermost anchored
+// resource is the same rule in both drafts.
+const DRAFT2019_SCHEMAS = new Set([
+  'https://json-schema.org/draft/2019-09/schema',
+  'https://json-schema.org/draft/2019-09/schema#',
+])
+const RECURSIVE_ANCHOR = '__ata_recursive_anchor'
+
+function isDraft2019(schema) {
+  return !!(schema && typeof schema.$schema === 'string' && DRAFT2019_SCHEMAS.has(schema.$schema))
+}
+
+const SUB_OBJECT = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+const SUB_ARRAY = ['allOf', 'anyOf', 'oneOf', 'prefixItems', 'items']
+const SUB_SINGLE = ['items', 'additionalItems', 'contains', 'not', 'if', 'then', 'else', 'additionalProperties',
+  'propertyNames', 'unevaluatedItems', 'unevaluatedProperties', 'contentSchema']
+
+function normalizeDraft2019(schema, force) {
+  if (!force && !isDraft2019(schema)) return schema
+  _normalize2019(schema, schema, false)
+  return schema
+}
+
+function _normalize2019(node, resourceRoot, isRoot) {
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) return
+  // A subschema with its own `$id` starts a new resource.
+  const root = !isRoot && typeof node.$id === 'string' && !node.$id.startsWith('#') ? node : resourceRoot
+  if (node.$recursiveAnchor === true && node === root) node.$dynamicAnchor = RECURSIVE_ANCHOR
+  delete node.$recursiveAnchor
+  if (typeof node.$recursiveRef === 'string') {
+    if (node.$recursiveRef === '#' && root.$dynamicAnchor === RECURSIVE_ANCHOR) node.$dynamicRef = '#' + RECURSIVE_ANCHOR
+    else if (node.$ref === undefined) node.$ref = node.$recursiveRef
+    delete node.$recursiveRef
+  }
+  // Recurse before the items rewrite, so tuple members are walked as members.
+  for (const key of SUB_OBJECT) {
+    const sub = node[key]
+    if (sub && typeof sub === 'object') for (const v of Object.values(sub)) _normalize2019(v, root, false)
+  }
+  for (const key of SUB_ARRAY) {
+    if (Array.isArray(node[key])) for (const v of node[key]) _normalize2019(v, root, false)
+  }
+  for (const key of SUB_SINGLE) {
+    const sub = node[key]
+    if (sub && typeof sub === 'object' && !Array.isArray(sub)) _normalize2019(sub, root, false)
+  }
+  if (Array.isArray(node.items)) {
+    node.prefixItems = node.items
+    if (node.additionalItems !== undefined) { node.items = node.additionalItems; delete node.additionalItems } else delete node.items
+  } else {
+    delete node.additionalItems
+  }
+}
+
+// The draft a `$schema` value names, for the normalizers: 2 draft-06,
+// 1 draft-07, 3 2019-09, 0 anything else. Takes the string so the caller
+// reads the property once.
+function draftCode(uri) {
+  if (typeof uri !== 'string') return 0
+  if (DRAFT6_SCHEMAS.has(uri)) return 2
+  if (DRAFT7_SCHEMAS.has(uri)) return 1
+  if (DRAFT2019_SCHEMAS.has(uri)) return 3
+  return 0
+}
+
+module.exports = { draftCode, isDraft7, isDraft6, isDraft2019, normalizeDraft2019, normalizeDraft7, normalizeNullable, normalizeExclusiveBounds, stripFormatAssertions }

package/lib/enrich-error.js

@@ -77,7 +77,19 @@ function reprValue (v) {
   if (t === 'number' || t === 'boolean') return String(v);
   if (Array.isArray(v)) return `[array, ${v.length} items]`;
   if (t === 'object') {
-    if (jsonSizeWithin(v, 60) >= 0) {
+    // The keys first: every key costs at least five characters serialised
+    // (`"k":` and a one-character value), so past twelve keys the 60-character
+    // body is out of reach and the size walk is skipped. The count is what the
+    // fallback prints, so it is taken once either way; the walk and the
+    // serialisation used to run on every container an error named, and a
+    // `required` or `unevaluatedProperties` error names its container.
+    let n;
+    try {
+      n = Object.keys(v).length;
+    } catch {
+      return '[object, unserializable]';
+    }
+    if (n <= 12 && jsonSizeWithin(v, 60) >= 0) {
       try {
         const s = JSON.stringify(v);
         if (s !== undefined && s.length <= 60) return s;
@@ -85,12 +97,6 @@ function reprValue (v) {
         return '[object, unserializable]';
       }
     }
-    let n;
-    try {
-      n = Object.keys(v).length;
-    } catch {
-      return '[object, unserializable]';
-    }
     return `[object, ${n} ${n === 1 ? 'key' : 'keys'}]`;
   }
   return `[${t}]`;
@@ -131,11 +137,12 @@ function resolveAt (err, data) {
  */
 // Observation-first wording. `message` stays as it is for parity, so this is a
 // separate field a consumer opts into.
-function detailFor (err, out) {
+function detailFor (err, out, at) {
   const p = err.params || {};
   switch (err.keyword) {
     case 'type':
-      return `expected ${p.type}, found ${typeNameOf(out.received)}`;
+      // From the value when the caller resolved it; from the repr otherwise.
+      return `expected ${p.type}, found ${(at === undefined || at === MISSING ? null : typeNameOfValue(at)) || typeNameOf(out.received)}`;
     case 'required':
       return `missing required property "${p.missingProperty}"`;
     case 'additionalProperties':
@@ -157,6 +164,24 @@ function detailFor (err, out) {
   }
 }
 
+// The same names from the value itself, for the callers that hold it: the
+// repr is a string built to be read, and parsing it back cost a regex per
+// type error. Agrees with typeNameOf on every value reprValue can produce:
+// a number that is not finite prints as NaN or Infinity, which the repr
+// parser calls a value, and so does this.
+// An object with its own toJSON prints as whatever that returns, so it is
+// left to the repr route (null here).
+function typeNameOfValue (v) {
+  if (v === null) return 'null';
+  switch (typeof v) {
+    case 'boolean': return 'boolean';
+    case 'string': return 'string';
+    case 'number': return Number.isFinite(v) ? 'number' : 'value';
+    case 'object': return Array.isArray(v) ? 'array' : typeof v.toJSON === 'function' ? null : 'object';
+    default: return 'value';
+  }
+}
+
 // Derived from the repr in `received`, which is already a JSON-ish string.
 function typeNameOf (received) {
   if (received === undefined) return 'nothing';
@@ -252,11 +277,25 @@ function enrich (rawErr, opts) {
   // renderer can surface the closest variant's diagnostics. They are enriched
   // like any other error: passed through raw, they carried whatever the engine
   // that answered wrote, the generator's internal ordering key included.
-  if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors.map((b) => enrich(b, data !== undefined ? { data } : null));
+  // A branch error the rich combined function already built is kept:
+  // enriching it again recomputed every field to the same values, and a
+  // collapsed oneOf paid that for each branch error on top of its own
+  // enrichment. Such an error carries `rank`, which only this enrichment and
+  // makeRich write; a standalone module's error carries a docUrl but no
+  // rank and is enriched as before (fromCompiled wraps those).
+  if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors.map((b) => (b !== null && typeof b === 'object' && b.rank !== undefined && b.docUrl !== undefined && b._o === undefined) ? b : enrich(b, data !== undefined ? { data } : null));
 
+  // The frames come from the position map, which is a walk of the document.
+  // Given lazily (validateJSON's rejections), the walk waits for the first
+  // read of any error's `dataFrame` or `anchor`: a caller that reads the
+  // messages and paths never pays for it, and one that reads every frame
+  // pays once, as before. Given eagerly, the fields are set as before.
+  const named = (rawErr.params && (rawErr.params.additionalProperty || rawErr.params.unevaluatedProperty)) || null;
   if (positions && positions[path]) {
     const p = positions[path];
     out.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+  } else if (!positions && opts && opts.lazyPositions) {
+    defineLazyFrames(out, path, named, opts.lazyPositions);
   }
 
   // Attach schema source frame when the validator was constructed with a
@@ -278,7 +317,7 @@ function enrich (rawErr, opts) {
   const sugg = suggestFor(out, data, at === MISSING ? undefined : at);
   if (sugg) out.suggestion = sugg;
 
-  const detail = detailFor(rawErr, out);
+  const detail = detailFor(rawErr, out, at);
   if (detail !== undefined) out.detail = detail;
   out.rank = st.rank;
 
@@ -286,7 +325,6 @@ function enrich (rawErr, opts) {
   // adds the key span so a caret can sit on the property that is wrong rather
   // than on the object containing it.
   if (opts && opts.positions) {
-    const named = (rawErr.params && (rawErr.params.additionalProperty || rawErr.params.unevaluatedProperty)) || null;
     const own = opts.positions[path];
     const child = named ? opts.positions[(path === '' ? '' : path) + '/' + named] : null;
     const src = child || own;
@@ -303,4 +341,42 @@ function enrich (rawErr, opts) {
   return out;
 }
 
+// `dataFrame` and `anchor` as accessors that resolve the position map on the
+// first read of either, on any error of the list (the map is shared through
+// `lazy`), and then become plain data properties, or go away when the map has
+// no entry for the error, which is the shape the eager path gives. Both are
+// enumerable, so JSON.stringify and a deep comparison read them as values;
+// a write replaces the accessor the way an assignment to a plain field would.
+function defineLazyFrames (out, path, named, lazy) {
+  let done = false;
+  let frames = null;
+  const resolve = () => {
+    if (done) return frames;
+    done = true;
+    const positions = lazy();
+    const own = positions ? positions[path] : null;
+    const dataFrame = own ? { byteOffset: own.byteOffset, length: own.length, line: own.line, col: own.col, text: own.text } : undefined;
+    const child = positions && named ? positions[(path === '' ? '' : path) + '/' + named] : null;
+    const src = child || own;
+    let anchor;
+    if (src) {
+      anchor = { line: src.line, col: src.col, length: src.length };
+      if (src.keyOffset !== undefined) {
+        anchor.keyLine = src.keyLine;
+        anchor.keyCol = src.keyCol;
+        anchor.keyLength = src.keyLength;
+      }
+    }
+    frames = { dataFrame, anchor };
+    if (dataFrame !== undefined) Object.defineProperty(out, 'dataFrame', { value: dataFrame, enumerable: true, configurable: true, writable: true });
+    else delete out.dataFrame;
+    if (anchor !== undefined) Object.defineProperty(out, 'anchor', { value: anchor, enumerable: true, configurable: true, writable: true });
+    else delete out.anchor;
+    return frames;
+  };
+  const settable = (name) => (v) => Object.defineProperty(out, name, { value: v, enumerable: true, configurable: true, writable: true });
+  Object.defineProperty(out, 'dataFrame', { get () { return resolve().dataFrame; }, set: settable('dataFrame'), enumerable: true, configurable: true });
+  Object.defineProperty(out, 'anchor', { get () { return resolve().anchor; }, set: settable('anchor'), enumerable: true, configurable: true });
+}
+
 module.exports = { enrich, reprValue, expectedFor, detailFor, rankFor, MISSING, DOC_BASE };

package/lib/enrich-site.js

@@ -49,7 +49,7 @@ function makeRich (site, path, params, message, value, root, spPrefix) {
   };
   const sugg = suggestFor(out, root, at === MISSING ? undefined : at);
   if (sugg) out.suggestion = sugg;
-  const detail = detailFor({ keyword: site.keyword, params }, out);
+  const detail = detailFor({ keyword: site.keyword, params }, out, at);
   if (detail !== undefined) out.detail = detail;
   out.rank = site.rank;
   return out;