ata-validator 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.3.0 - 2026-08-02
+
+### Added
+
+- `useDefaults` and `assertFormat` validator options, both defaulting to `true` so existing behavior is unchanged. `useDefaults: false` stops missing properties being filled in from their `default` before validation, which matters because a `default` that does not satisfy its own subschema currently makes an otherwise valid instance fail. `assertFormat: false` treats `format` as an annotation rather than an assertion, the Draft 2020-12 reading when the format-assertion vocabulary is not in use. With both off, ata passes every case in the suite's `format` and `default` files.
+
+### Fixed
+
+- A `$ref` that could not be resolved validated everything instead of failing. The JS compiler emitted no check at all for an unresolved reference, so a typo in a `$ref`, or a reference into a schema that was never registered, silently turned off every constraint behind it rather than reporting an error. Both compiler paths now decline to compile such a schema and it validates on the interpreted engine, which reports `ATA5001` naming the reference it could not resolve.
+- References that resolve relative to an enclosing base URI are no longer compiled by the JS paths, which match registry entries by exact key or path suffix and have no notion of a base. Nested `$id` scopes, relative references, and documents registered under a URI different from the `$id` they declare now route to the interpreted engine, which tracks the base properly. Schemas that reference a flat registry of ids, the common `$ref: 'shared#'` shape, still take the compiled fast path.
+- A schema supplied through the `schemas` option as a URI-keyed record was registered only under the `$id` it declared, so references to the URI it was registered under could not resolve. It is now addressable by both.
+- Official draft 2020-12 remote-reference suite: 30 of 31 cases, up from 21. Pure-JS configuration on the full suite: 1189 of 1190, up from 1188. The native configuration stays at 1190 of 1190.
+
 ## 1.2.2 - 2026-07-26
 
 ### Fixed

package/index.d.ts

@@ -317,6 +317,19 @@ export type ValidateAndParseResult<T = unknown> =
 export interface ValidatorOptions {
   coerceTypes?: boolean;
   removeAdditional?: boolean;
+  /**
+   * When true (default), missing properties are filled in from their `default`
+   * before validation. Set to false to leave the instance untouched, which is
+   * what the specification describes: `default` is an annotation and never
+   * affects whether an instance is valid.
+   */
+  useDefaults?: boolean;
+  /**
+   * When true (default), `format` is asserted and a value that does not match
+   * its format fails. Set to false to treat `format` as an annotation, the
+   * Draft 2020-12 behavior when the format-assertion vocabulary is not in use.
+   */
+  assertFormat?: boolean;
   schemas?: Record<string, object> | object[];
   /**
    * Custom format checkers. Keys are format names referenced from `format` in

package/index.js

@@ -9,7 +9,7 @@ const {
   compileToJSCodegenWithErrors,
   compileToJSCombined,
 } = require("./lib/js-compiler");
-const { normalizeDraft7, normalizeNullable } = require("./lib/draft7");
+const { normalizeDraft7, normalizeNullable, stripFormatAssertions } = require("./lib/draft7");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
 
@@ -250,11 +250,13 @@ function buildPreprocessCodegen(schema, options) {
   }
 
   // defaults: inline per property
-  for (const [key, prop] of Object.entries(props)) {
-    if (prop && typeof prop === 'object' && prop.default !== undefined) {
-      const k = JSON.stringify(key);
-      const def = JSON.stringify(prop.default);
-      lines.push(`if(!(${k} in d))d[${k}]=${def}`);
+  if (options.useDefaults !== false) {
+    for (const [key, prop] of Object.entries(props)) {
+      if (prop && typeof prop === 'object' && prop.default !== undefined) {
+        const k = JSON.stringify(key);
+        const def = JSON.stringify(prop.default);
+        lines.push(`if(!(${k} in d))d[${k}]=${def}`);
+      }
     }
   }
 
@@ -435,7 +437,11 @@ function buildSchemaMap(schemas) {
   } else {
     for (const [key, s] of Object.entries(schemas)) {
       const normalized = _normalizeCallerSchema(s)
-      map.set(normalized.$id || key, normalized)
+      // A retrieved document is addressable both by the URI it was registered
+      // under and by the $id it declares. Registering only the $id makes
+      // references to the retrieval URI unresolvable.
+      map.set(key, normalized)
+      if (normalized.$id && normalized.$id !== key) map.set(normalized.$id, normalized)
     }
   }
   return map
@@ -537,10 +543,18 @@ class Validator {
     // When schema is a string, JSON.parse already produces a fresh object.
     // When schema is an object, normalization runs on a clone so the caller's
     // object is never touched.
-    const schemaObj = typeof schema === "string"
+    let schemaObj = typeof schema === "string"
       ? JSON.parse(schema)
       : _normalizeCallerSchema(schema);
 
+    // assertFormat: false makes `format` annotation-only. Strip it on a clone
+    // so the caller's schema keeps the keyword.
+    if (options.assertFormat === false) {
+      schemaObj = stripFormatAssertions(
+        schemaObj === schema ? _deepCloneWithSymbols(schemaObj) : schemaObj,
+      );
+    }
+
     this._schemaStr = null; // lazy: computed on first use
     this._schemaObj = schemaObj;
     this._options = options;
@@ -722,7 +736,7 @@ class Validator {
     const preprocessSchema = resolveSchemaForPreprocess(schemaObj, this._schemaMap);
     let preprocess = buildPreprocessCodegen(preprocessSchema, options);
     if (!preprocess) {
-      const applyDefaults = buildDefaultsApplier(preprocessSchema);
+      const applyDefaults = options.useDefaults === false ? null : buildDefaultsApplier(preprocessSchema);
       const applyCoerce = options.coerceTypes ? buildCoercer(preprocessSchema) : null;
       const applyRemove = options.removeAdditional
         ? buildRemover(preprocessSchema)

package/lib/draft7.js

@@ -126,4 +126,46 @@ function _normalizeNullable(schema) {
   }
 }
 
-module.exports = { isDraft7, normalizeDraft7, normalizeNullable }
+// Draft 2020-12 treats `format` as an annotation unless the assertion
+// vocabulary is in use. Removing the keyword is exactly that reading, and it
+// keeps every engine in agreement without each one growing its own switch.
+// Walks schema-bearing keywords only, so a property or definition named
+// "format" is untouched.
+function stripFormatAssertions(schema) {
+  if (typeof schema !== 'object' || schema === null) return schema
+  _stripFormat(schema, new Set())
+  return schema
+}
+
+function _stripFormat(schema, seen) {
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) return
+  if (seen.has(schema)) return
+  seen.add(schema)
+
+  if (typeof schema.format === 'string') delete schema.format
+
+  const objSubs = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+  for (const key of objSubs) {
+    if (schema[key] && typeof schema[key] === 'object' && !Array.isArray(schema[key])) {
+      for (const v of Object.values(schema[key])) _stripFormat(v, seen)
+    }
+  }
+  const arrSubs = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+  for (const key of arrSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const s of schema[key]) _stripFormat(s, seen)
+    }
+  }
+  const singleSubs = ['items', 'additionalItems', 'contains', 'not', 'if', 'then', 'else',
+                      'additionalProperties', 'propertyNames', 'unevaluatedItems',
+                      'unevaluatedProperties', 'contentSchema']
+  for (const key of singleSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const s of schema[key]) _stripFormat(s, seen)
+    } else {
+      _stripFormat(schema[key], seen)
+    }
+  }
+}
+
+module.exports = { isDraft7, normalizeDraft7, normalizeNullable, stripFormatAssertions }

package/lib/js-compiler.js

@@ -107,6 +107,8 @@ function compileToJS(schema, defs, schemaMap) {
     if (!hasDynamic && hasNestedIdScope(schema)) return null
   }
 
+  if (!defs && needsBaseTracking(schema, schemaMap, new Set())) return null
+
   // Collect $defs early so sub-schemas can resolve $ref
   const rootDefs = defs || collectDefs(schema)
 
@@ -611,27 +613,23 @@ function resolveRef(ref, defs, schemaMap) {
       if (entry) return (d) => { const fn = entry.fn; return fn ? fn(d) : true }
     }
   }
+  // A referenced schema that cannot itself be compiled must propagate the bail.
+  // Substituting an always-true function here would make the reference vacuous
+  // and silently drop every constraint behind it.
   // 2. Cross-schema ref (exact match)
   if (schemaMap && schemaMap.has(ref)) {
-    const resolved = schemaMap.get(ref)
-    const fn = compileToJS(resolved, null, schemaMap)
-    return fn || (() => true)
+    return compileToJS(schemaMap.get(ref), null, schemaMap)
   }
   // 3. Cross-schema ref with JSON pointer fragment ("<id>#/<path>")
   if (schemaMap && ref.includes('#')) {
     const r = resolveCrossSchemaRef(ref, schemaMap)
-    if (r) {
-      const fn = compileToJS(r.schema, null, schemaMap)
-      return fn || (() => true)
-    }
+    if (r) return compileToJS(r.schema, null, schemaMap)
   }
   // 4. Cross-schema ref (relative URI resolution, no fragment)
   if (schemaMap && !ref.includes('://') && !ref.startsWith('#')) {
     for (const [id] of schemaMap) {
       if (id.endsWith('/' + ref)) {
-        const resolved = schemaMap.get(id)
-        const fn = compileToJS(resolved, null, schemaMap)
-        return fn || (() => true)
+        return compileToJS(schemaMap.get(id), null, schemaMap)
       }
     }
   }
@@ -933,6 +931,169 @@ function hasAdditionalPropertiesSchema(schema) {
   return false
 }
 
+// Schema-bearing keywords, so the walk below never mistakes a property named
+// "$ref" for an actual reference.
+const SUBSCHEMA_MAPS = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+const SUBSCHEMA_LISTS = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+const SUBSCHEMA_SINGLES = ['items', 'additionalItems', 'contains', 'not', 'if', 'then', 'else',
+  'additionalProperties', 'propertyNames', 'unevaluatedItems', 'unevaluatedProperties', 'contentSchema']
+
+// genCode emits nothing for a $ref it cannot resolve, which makes the reference
+// silently vacuous — a typo in a $ref would turn validation off rather than
+// fail. Codegen bails instead, so the schema routes to the interpreted engine,
+// which reports the unresolved reference as an error. Mirrors genCode's own
+// resolution rules; anything genCode cannot resolve is treated as unresolvable.
+function refResolves(ref, rootDefs, anchors, schemaMap) {
+  if (ref === '#') return true
+  const local = ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/)
+  if (local) return !!(rootDefs && rootDefs[local[1]])
+  if (ref.startsWith('#') && !ref.startsWith('#/')) {
+    const entry = rootDefs && rootDefs[ref]
+    return !!((entry && entry.raw) || (anchors && anchors[ref]))
+  }
+  if (ref.startsWith('#')) return false
+  if (!schemaMap) return false
+  if (schemaMap.has(ref)) return true
+  if (!ref.includes('://')) {
+    for (const [id] of schemaMap) if (id.endsWith('/' + ref)) return true
+  }
+  if (ref.includes('#')) return !!resolveCrossSchemaRef(ref, schemaMap)
+  return false
+}
+
+// Resolve a $ref that crosses into another document, mirroring genCode's rules.
+function crossDocTarget(ref, schemaMap) {
+  if (!schemaMap || ref.startsWith('#')) return null
+  if (schemaMap.has(ref)) return schemaMap.get(ref)
+  if (!ref.includes('://')) {
+    for (const [id, s] of schemaMap) if (id.endsWith('/' + ref)) return s
+  }
+  if (ref.includes('#')) {
+    const r = resolveCrossSchemaRef(ref, schemaMap)
+    if (r) return r.schema
+  }
+  return null
+}
+
+// True when a subtree contains a fragment-only reference ("#", "#/$defs/x",
+// "#anchor"). Such a reference is relative to the document that holds it.
+function subtreeHasLocalRef(node, seen) {
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) return false
+  if (seen.has(node)) return false
+  seen.add(node)
+  if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true
+  for (const key of SUBSCHEMA_MAPS) {
+    const group = node[key]
+    if (group && typeof group === 'object' && !Array.isArray(group)) {
+      for (const sub of Object.values(group)) if (subtreeHasLocalRef(sub, seen)) return true
+    }
+  }
+  for (const key of SUBSCHEMA_LISTS) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) if (subtreeHasLocalRef(sub, seen)) return true
+    }
+  }
+  for (const key of SUBSCHEMA_SINGLES) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) if (subtreeHasLocalRef(sub, seen)) return true
+    } else if (subtreeHasLocalRef(node[key], seen)) return true
+  }
+  return false
+}
+
+// Neither JS path tracks the base URI a reference is resolved against: they
+// match registry keys by exact string or by path suffix. That is fine for a
+// flat registry of absolute ids, but wrong as soon as resolution depends on an
+// enclosing scope. These shapes go to the interpreted engine, which resolves
+// against a real base.
+function needsBaseTracking(schema, schemaMap, seen) {
+  if (!schemaMap || schemaMap.size === 0) return false
+  // A nested $id opens a new scope that later relative references resolve
+  // against.
+  if (hasNestedIdScope(schema)) return true
+  return refsAreScopeSensitive(schema, schemaMap, seen)
+}
+
+function refsAreScopeSensitive(node, schemaMap, seen) {
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) return false
+  if (seen.has(node)) return false
+  seen.add(node)
+
+  const ref = node.$ref
+  if (typeof ref === 'string' && !ref.startsWith('#')) {
+    const key = ref.split('#')[0]
+    // A key the registry holds verbatim needs no base to resolve — this is the
+    // flat-registry case ($ref: 'shared#'). Anything else that is not absolute
+    // only resolves by walking up from an enclosing base.
+    if (!schemaMap.has(key) && !ref.includes('://')) return true
+    const target = crossDocTarget(ref, schemaMap)
+    if (target && typeof target === 'object') {
+      // Registered under a key that differs from the $id it declares, so its
+      // own references resolve against a different base than its retrieval URI.
+      if (typeof target.$id === 'string' && target.$id !== key) return true
+      if (subtreeHasLocalRef(target, new Set()) && refsAreScopeSensitive(target, schemaMap, seen)) return true
+    }
+  }
+
+  for (const key of SUBSCHEMA_MAPS) {
+    const group = node[key]
+    if (group && typeof group === 'object' && !Array.isArray(group)) {
+      for (const sub of Object.values(group)) if (refsAreScopeSensitive(sub, schemaMap, seen)) return true
+    }
+  }
+  for (const key of SUBSCHEMA_LISTS) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) if (refsAreScopeSensitive(sub, schemaMap, seen)) return true
+    }
+  }
+  for (const key of SUBSCHEMA_SINGLES) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) if (refsAreScopeSensitive(sub, schemaMap, seen)) return true
+    } else if (refsAreScopeSensitive(node[key], schemaMap, seen)) return true
+  }
+  return false
+}
+
+function hasUnresolvableRef(node, rootDefs, anchors, schemaMap, seen) {
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) return false
+  if (seen.has(node)) return false
+  seen.add(node)
+
+  if (typeof node.$ref === 'string') {
+    if (!refResolves(node.$ref, rootDefs, anchors, schemaMap)) return true
+    // Following a reference into another document changes the base URI, which
+    // codegen does not track: it would resolve the target's own fragment-only
+    // references against the entry schema instead. Bail so the interpreted
+    // engine, which does track the base, handles it.
+    const target = crossDocTarget(node.$ref, schemaMap)
+    if (target && subtreeHasLocalRef(target, new Set())) return true
+  }
+
+  for (const key of SUBSCHEMA_MAPS) {
+    const group = node[key]
+    if (group && typeof group === 'object' && !Array.isArray(group)) {
+      for (const sub of Object.values(group)) {
+        if (hasUnresolvableRef(sub, rootDefs, anchors, schemaMap, seen)) return true
+      }
+    }
+  }
+  for (const key of SUBSCHEMA_LISTS) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) {
+        if (hasUnresolvableRef(sub, rootDefs, anchors, schemaMap, seen)) return true
+      }
+    }
+  }
+  for (const key of SUBSCHEMA_SINGLES) {
+    if (Array.isArray(node[key])) {
+      for (const sub of node[key]) {
+        if (hasUnresolvableRef(sub, rootDefs, anchors, schemaMap, seen)) return true
+      }
+    } else if (hasUnresolvableRef(node[key], rootDefs, anchors, schemaMap, seen)) return true
+  }
+  return false
+}
+
 // --- Codegen mode: generates a single Function (NOT CSP-safe) ---
 // This matches ajv's approach: one monolithic function, V8 JIT fully inlines it
 function compileToJSCodegen(schema, schemaMap, userFormats) {
@@ -998,6 +1159,9 @@ function compileToJSCodegen(schema, schemaMap, userFormats) {
     }
   }
 
+  if (hasUnresolvableRef(schema, rootDefs, anchors, schemaMap, new Set())) return null
+  if (needsBaseTracking(schema, schemaMap, new Set())) return null
+
   const ctx = { varCounter: 0, helpers: [], helperCode: [], preamble: [], closureVars: ['_cpLen'], closureVals: [_cpLen], rootDefs, refStack: new Set(), schemaMap: schemaMap || null, anchors, rootSchema: schema, userFormats: userFormats || null }
   const lines = []
   genCode(schema, 'd', lines, ctx)

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -112,12 +112,12 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.2.2",
-    "@ata-validator/native-linux-x64-gnu": "1.2.2",
-    "@ata-validator/native-linux-arm64-gnu": "1.2.2",
-    "@ata-validator/native-linux-x64-musl": "1.2.2",
-    "@ata-validator/native-linux-arm64-musl": "1.2.2",
-    "@ata-validator/native-win32-x64": "1.2.2"
+    "@ata-validator/native-darwin-arm64": "1.3.0",
+    "@ata-validator/native-linux-x64-gnu": "1.3.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.3.0",
+    "@ata-validator/native-linux-x64-musl": "1.3.0",
+    "@ata-validator/native-linux-arm64-musl": "1.3.0",
+    "@ata-validator/native-win32-x64": "1.3.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"