ata-validator 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.6.0 - 2026-08-08
+
+### Added
+
+- The JSON Schema v1 dialect. A schema declaring `"$schema": "https://json-schema.org/v1"`, or the dated `https://json-schema.org/v1/2026` the specification repository's meta-schema carries, is now validated under v1 rather than under 2020-12. The difference ata implements is `$dynamicRef`: v1 removes the bookending requirement, so a reference resolves through the dynamic scope whether or not the schema it initially lands on carries a matching `$dynamicAnchor`, and also when it resolves to nothing on its own. The outermost matching anchor still in scope wins, as before. `propertyDependencies`, the other v1 addition, shipped in 1.5.0.
+- Against the suite's `v1` directory with nothing excluded, ata scores 1123 of 1127. The four it misses are the same four that fail on 2020-12: one `$dynamicRef` scope corner each engine misses, a definition validated against the meta-schema, and two remote-reference cases. `npm run test:suite` now runs the dialect alongside 2020-12 and draft 7, `tests/test_no_eval.js` runs it with code generation blocked (1124 of 1127 there), and `tests/test_v1_dialect.js` checks the switch itself: the same document must not validate the same way under both dialects.
+- Only `$dynamicRef` routing changes. Everything else ata implements is identical under v1 and 2020-12, so a v1 schema that does not use the keyword takes the same compiled path it always did. One that does use it validates on the interpreted engine, since the JS compiler and the native addon both resolve the 2020-12 way. The native engine does not implement bookending at all, which is invisible to the official 2020-12 suite but means it cannot be trusted to answer for either dialect here.
+
 ## 1.5.1 - 2026-08-07
 
 ### Fixed

package/README.md

@@ -461,8 +461,17 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 | Enum/Const | `enum`, `const` |
 | Composition | `allOf`, `anyOf`, `oneOf`, `not` |
 | Conditional | `if`, `then`, `else` |
-| References | `$ref`, `$defs`, `definitions`, `$id` |
+| References | `$ref`, `$defs`, `definitions`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` |
 | Boolean | `true`, `false` |
+| v1 | `propertyDependencies` |
+
+### 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.
+
+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.
+
+Both are implemented in the interpreted engine, so a v1 schema that uses `$dynamicRef` validates there rather than through the compiler or the native addon, which resolve the 2020-12 way. Schemas that use neither keyword take the same compiled path they always did.
 
 ### Format Validators (hand-written, no regex)
 
@@ -470,12 +479,12 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 
 ### Known limitations
 
-Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1285 of 1290 cases, 99.6%. Draft 7 gives 911 of 922, 98.8%. `npm run test:suite` reproduces both and lists the remaining failures by name.
+Running the whole Draft 2020-12 suite with nothing excluded, `format` and `default` under specification semantics (`assertFormat: false`, `useDefaults: false`), gives 1285 of 1290 cases, 99.6%. Draft 7 gives 911 of 922, 98.8%. The v1 dialect gives 1123 of 1127, 99.6%, and the four it misses are the same four that fail on 2020-12. `npm run test:suite` reproduces all three and lists the remaining failures by name.
 
 Areas that remain deliberate scope decisions for 1.x:
 
 - **Remote `$ref` over the network** is not fetched. Register cross-schema refs explicitly with `schemas: [...]` or `addSchema()`.
-- **`$vocabulary`** is not implemented; custom vocabularies are ignored rather than enforced.
+- **`$vocabulary`** is not implemented; custom vocabularies are ignored rather than enforced. The keyword was extracted from the specification for the stable release as incomplete, so it is not part of v1.
 - **`contentEncoding` / `contentMediaType` / `contentSchema`** are annotation-only, as the spec permits, and are not validated.
 - **`minLength`/`maxLength`** count UTF-16 code units, not grapheme clusters.
 - **Infinite-loop detection** relies on a recursion depth guard that cuts off circular `$ref` chains.

package/index.js

@@ -10,6 +10,7 @@ const {
   compileToJSCombined,
 } = require("./lib/js-compiler");
 const { normalizeDraft7, normalizeNullable, stripFormatAssertions } = require("./lib/draft7");
+const { isV1Dialect } = require("./lib/dialect");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
 
@@ -724,11 +725,22 @@ class Validator {
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
     let jsFn, jsCombinedFn, jsErrFn, _isCodegen = false;
     var _forceNapi = typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI;
-    // Where source cannot be turned into a function, neither JS path is usable.
-    // The closure path does not call `new Function` itself, so it survives the
-    // block and would quietly handle schemas it gets wrong; the interpreted
-    // engine is both eval-free and more correct, so go straight there.
-    if (!codegenAvailable()) {
+    // v1 removes the bookending requirement for $dynamicRef. Only the
+    // interpreted engine implements that; the JS compiler and the native
+    // engine both resolve the 2020-12 way, so a v1 schema using the keyword
+    // goes to the interpreter rather than being validated under the wrong
+    // dialect. Schemas without $dynamicRef are unaffected: v1 and 2020-12
+    // agree on everything else ata implements.
+    this._v1Dynamic =
+      isV1Dialect(schemaObj) &&
+      (this._schemaStr.includes('"$dynamicRef"') || this._schemaStr.includes('"$dynamicAnchor"'));
+    //
+    // Where source cannot be turned into a function, neither JS path is usable
+    // either. The closure path does not call `new Function` itself, so it
+    // survives the block and would quietly handle schemas it gets wrong; the
+    // interpreted engine is both eval-free and more correct, so go straight
+    // there.
+    if (this._v1Dynamic || !codegenAvailable()) {
       jsFn = null; jsCombinedFn = null; jsErrFn = null;
     } else if (cached && !_forceNapi) {
       jsFn = cached.jsFn;
@@ -812,6 +824,7 @@ class Validator {
           _interp = createInterpreter(schemaObj, {
             schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
             formats: this._userFormats,
+            v1: isV1Dialect(schemaObj),
           });
         }
         const r = _interp.validate(d);
@@ -1065,7 +1078,7 @@ class Validator {
       // using it goes there even when it also uses $dynamicRef.
       const _hasPropDeps = this._schemaStr.includes('"propertyDependencies"')
       let _validate;
-      if (_hasDynRef && !_hasUneval && !_hasPropDeps) {
+      if (_hasDynRef && !_hasUneval && !_hasPropDeps && !this._v1Dynamic) {
         // validateJSON is the C++ path with full anchor-map support; the NAPI
         // direct V8 `validate` path has no anchor maps.
         _validate = (data) => this._compiled.validateJSON(JSON.stringify(data));
@@ -1076,6 +1089,7 @@ class Validator {
         const interp = createInterpreter(schemaObj, {
           schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
           formats: this._userFormats,
+          v1: isV1Dialect(schemaObj),
         });
         _validate = (data) => interp.validate(data);
         this.validateJSON = (jsonStr) => {
@@ -1133,6 +1147,7 @@ class Validator {
       const interp = createInterpreter(schemaObj, {
         schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
         formats: this._userFormats,
+        v1: isV1Dialect(schemaObj),
       });
       const run = preprocess
         ? (data) => { preprocess(data); return interp.validate(data); }

package/lib/dialect.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Dialect detection.
+//
+// Only the v1 dialect is distinguished here, and only because v1 changes
+// behavior that is otherwise identical to 2020-12: the bookending requirement
+// for `$dynamicRef` is removed. Everything else ata does under 2020-12 is
+// unchanged under v1, so a schema that declares no `$schema` keeps the
+// existing default rather than being guessed at.
+//
+// The official test suite states the dialect as `https://json-schema.org/v1`.
+// The meta-schema in the specification repository carries the dated
+// `https://json-schema.org/v1/2026`. Both name the same dialect, and
+// `draft/next` is the name the same work carried before the stable release was
+// numbered, so all three are accepted.
+const V1_DIALECTS = new Set([
+  'https://json-schema.org/v1',
+  'https://json-schema.org/v1/schema',
+  'https://json-schema.org/v1/2026',
+  'https://json-schema.org/draft/next/schema',
+]);
+
+function isV1Dialect(schema) {
+  if (typeof schema !== 'object' || schema === null) return false;
+  if (typeof schema.$schema !== 'string') return false;
+  // A trailing '#' is an empty fragment naming the same document.
+  const uri = schema.$schema.endsWith('#') ? schema.$schema.slice(0, -1) : schema.$schema;
+  return V1_DIALECTS.has(uri);
+}
+
+module.exports = { isV1Dialect, V1_DIALECTS };

package/lib/interpreter.js

@@ -265,6 +265,9 @@ class Interpreter {
     this.root = rootSchema;
     this.state = indexSchemas(rootSchema, opts.schemaMap);
     this.userFormats = opts.formats || null;
+    // 2020-12 requires bookending for `$dynamicRef`; v1 removes the
+    // requirement. See the `$dynamicRef` branch in eval().
+    this.bookending = !opts.v1;
     this.patternCache = new Map();
   }
 
@@ -337,11 +340,19 @@ class Interpreter {
       const ref = schema.$dynamicRef;
       let { node, base: refBase } = resolveRef(ref, base, this.state);
       const [, fragment] = splitFragment(resolveUri(base, ref));
-      if (node !== undefined && fragment && !fragment.startsWith('/')) {
-        // Initial target must itself carry the matching $dynamicAnchor for
-        // dynamic resolution; otherwise it behaves like $ref.
+      if (fragment && !fragment.startsWith('/')) {
+        // Under 2020-12 the initial target must itself carry the matching
+        // $dynamicAnchor before the dynamic scope is consulted (bookending);
+        // otherwise the keyword behaves like $ref. v1 removes that
+        // requirement, so the scope is searched whether or not the initial
+        // target carries the anchor, and also when the reference does not
+        // resolve on its own, which is the shape the suite uses: a
+        // `$dynamicRef` in a resource that declares no anchor of that name.
         const initialDyn = this.state.dynamicAnchors.get(refBase);
-        if (initialDyn && initialDyn.get(fragment) === node) {
+        const bookended = node !== undefined && initialDyn && initialDyn.get(fragment) === node;
+        if (bookended || !this.bookending) {
+          // Outermost scope first: the first matching $dynamicAnchor
+          // encountered while evaluating wins.
           for (const scopeBase of dynScope) {
             const dyn = this.state.dynamicAnchors.get(scopeBase);
             if (dyn && dyn.has(fragment)) {

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.5.1",
+  "version": "1.6.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",
@@ -44,9 +44,9 @@
     "release:check": "node scripts/regen-safe-regex-source.js && node tests/test_pack_purity.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
-    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_buffer_path_parity.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_order.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_order.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
-    "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7",
+    "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7 && node tests/run_suite.js v1",
     "test:compat": "node tests/test_compat.js",
     "test:standard-schema": "node tests/test_standard_schema.js",
     "test:browser": "node tests/test_browser.js",
@@ -112,12 +112,12 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.5.1",
-    "@ata-validator/native-linux-x64-gnu": "1.5.1",
-    "@ata-validator/native-linux-arm64-gnu": "1.5.1",
-    "@ata-validator/native-linux-x64-musl": "1.5.1",
-    "@ata-validator/native-linux-arm64-musl": "1.5.1",
-    "@ata-validator/native-win32-x64": "1.5.1"
+    "@ata-validator/native-darwin-arm64": "1.6.0",
+    "@ata-validator/native-linux-x64-gnu": "1.6.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.6.0",
+    "@ata-validator/native-linux-x64-musl": "1.6.0",
+    "@ata-validator/native-linux-arm64-musl": "1.6.0",
+    "@ata-validator/native-win32-x64": "1.6.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"