@texaryn/schema-json 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @texaryn/schema-json
 
+## 0.8.0
+
+### Minor Changes
+
+- 8605d64: Adds opt-in projected submissions and rejects reference scope collisions that give validation and projection different assertions. The runtime validates and submits the same independent snapshot while retaining live form data.
+- 82f38e9: Add explicit view expansion for recursion and budget boundaries.
+- 8605d64: Adds host supplied external schema resolution with a configurable resource limit.
+- 82f38e9: Adds opt in dynamic scope projection for supported local references and host supplied external resources.
+
+### Patch Changes
+
+- 1adb31d: Patches dependent schema reduction and includes the fixed runtime in published adapter builds, so invalid `oneOf` dependencies remain projectable for installed consumers.
+- 8605d64: Corrects projection through `allOf` references and applies dialect-specific defaults beside `$ref`.
+- 8605d64: Preserves inherited dialects and Draft 7 identifiers when compiling retrieved schemas.
+- 6f6bd70: Projects fields from retained inactive conditional branches and keeps them aligned with Hyperjump.
+- 8605d64: Projects fields from the selected Draft 7 `then` or `else` reference.
+- 82f38e9: Reuse static property candidates across data projections and skip reductions that cannot change an object's projected shape.
+- 82f38e9: Avoid repeated branch validation for missing values during a single schema projection.
+- 8605d64: Projects existing and required fields governed by `additionalProperties`.
+- Updated dependencies [8605d64]
+- Updated dependencies [82f38e9]
+- Updated dependencies [8605d64]
+  - @texaryn/core@0.14.0
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -85,6 +85,7 @@ The adapter currently handles the schema features required by Texaryn's runtime
 - arrays
 - enums
 - local `$ref`, including recursive references
+- opt-in dynamic scope projection for supported `$dynamicRef` and `$recursiveRef` paths
 - `if` / `then` / `else`
 - `oneOf`
 - `anyOf`
@@ -101,10 +102,29 @@ A local `$ref` may point back to a schema that contains it, such as `{ propertie
 
 `boundaries` on an object's `NodeProjection` says why the projection withheld something beneath it: `recursion` when a descendant would repeat the object's schemas, `budget` when a fixed per-projection limit withheld members. The limits are 16 objects and 512 nodes, counted only over locations that exist because of the recursion, two or more levels below the data; they never cut a member of a location that holds data. A node the projection reached only by expanding the recursion carries `recursiveExpansion`, and `schema-defaults` initialization never writes there.
 
+`boundaryTargets` has the next withheld instance pointer for each boundary reason, with a generation scoped token. Pass selected tokens to `project(data, { expandedBoundaryTokens })` to reveal those locations. The runtime also supplies `boundaryGeneration`; direct adapter callers can leave it at zero or increment it whenever replacing a container changes pointer ownership. Each token admits one target. The built in renderers show one action per boundary reason on an object and advance one target per click, so a large budget boundary does not create a button for every withheld field. Expansion changes the view only. It does not write form data, affect validation, or change initialization. React, React Bootstrap, React MUI, Vue, and Web Components provide these actions by default.
+
 A schema that applies itself at one instance location without crossing into a property or item, such as `{ allOf: [{ $ref: '#' }] }`, makes the evaluator recurse without end, so `createJsonSchemaAdapter` rejects it with `SameLocationCycleError`. Its `positions` field lists the schema positions of each cycle, and the message names one of them and the path through the cycle. The check reads the schema, not the data: a cycle behind an `if` is rejected even while the `if` does not hold, except the branches the specification never evaluates. It is conservative for dynamic references, treating a `$dynamicRef` to a `$dynamicAnchor` as reaching every `$dynamicAnchor` of that name and a `$recursiveRef` as reaching every schema that declares `$recursiveAnchor: true`, so a schema whose dynamic references could close such a cycle is rejected even when no evaluation selects it.
 
 The [JSON Schema support guide](https://texaryn.github.io/texaryn/guides/json-schema-support/#recursive-references) has the details, and ADR-007 records the decision.
 
+## Dynamic reference projection
+
+Dynamic scope aware form projection is opt in with `dynamicReferenceProjection: 'local'`. It supports Draft 2020-12 `$dynamicRef` and Draft 2019-09 `$recursiveRef: '#'` under object properties or homogeneous array items, including references reached through `allOf`, `anyOf`, `oneOf`, conditionals and `dependentSchemas`.
+
+External dynamic references use the host supplied `resolveResource` callback. The adapter does not fetch schemas. Without the option, the projector does not follow the active dynamic scope. The option rejects references below unsupported applicators and array keywords, root relative resource identifiers, and unsupported reference siblings. See [ADR-010](../../docs/adr/010-local-dynamic-reference-projection.md) for the exact boundaries.
+
+```ts
+const adapter = await createJsonSchemaAdapter(schema, {
+  dynamicReferenceProjection: 'local',
+  resolveResource: (uri) => schemaResources.get(uri),
+})
+```
+
+Adapter creation also rejects a retained static `$ref` when json-schema-library resolves it to different declarations with different validation assertions in the validation tree and the normalised projection tree. The check covers the dialect's supported assertions, including boolean subschemas. The error is `ProjectionValidationDivergenceError`.
+
+The adapter exposes `projectSubmission(data)` for supported schemas. It removes values declared only by inactive branches, keeps provisional fields, and preserves undeclared data so validation can still reject it. This opt-in treats an inactive declaration as form data to omit even when an enclosing object allows additional properties. `createFormRuntime` selects the mode with `submission: 'projected'`; it validates and submits the same independent snapshot, while the form's live data stays unchanged. Schemas with dynamic references or `unevaluatedProperties` or `unevaluatedItems` do not expose this capability yet. The private Hyperjump adapter also does not expose it. Runtime creation fails if projected submission is requested without the capability.
+
 ## json-schema-library version
 
 The dependency is pinned to exactly `11.6.2`. In Draft 7, json-schema-library 11.6.2 overwrites the registry entry that `"$ref": "#"` resolves through, so without a fix the reference reaches another node and validation is wrong. The adapter pins that entry to the document root, and every other entry the library files for its own location to the node compiled there, so a reduction during projection cannot replace a definition with a reduced copy. Because the fix depends on the library's internal registry, adapter creation throws an error naming json-schema-library 11.6.2 when the registry is shaped differently, or when a self-test on two probe schemas shows the fix no longer repairs validation. A newer json-schema-library release is not installed until a Texaryn release raises the pin after the registry fix and its self-test pass against it.
@@ -153,6 +173,7 @@ The result contains validation errors at that pointer or below it.
 ```ts
 import {
   createJsonSchemaAdapter,
+  ProjectionValidationDivergenceError,
   SameLocationCycleError,
   type AdapterConfig,
   type Dialect,
@@ -174,6 +195,9 @@ const adapter = await createJsonSchemaAdapter(schema, {
 ```ts
 interface AdapterConfig {
   defaultDialect?: Dialect
+  dynamicReferenceProjection?: 'local'
+  resolveResource?: (uri: string) => unknown | undefined | Promise<unknown | undefined>
+  maxExternalResources?: number
 }
 ```
 
@@ -198,6 +222,10 @@ try {
 }
 ```
 
+### `ProjectionValidationDivergenceError`
+
+Thrown by `createJsonSchemaAdapter` when one retained static `$ref` resolves to different declarations with different validation assertions for validation and projection. Its `reference` and `sourcePosition` identify the reference site. `validationPosition` and `projectionPosition` identify the two resolved schema positions.
+
 ## Architecture
 
 The adapter is deliberately separate from `@texaryn/core`:

package/THIRD-PARTY-NOTICES.md

@@ -1,5 +1,12 @@
 # Third-party notices
 
+## json-schema-library
+
+The ESM runtime at `dist/vendor/json-schema-library/` is adapted from
+`json-schema-library` 11.6.2 by Sascha Goldhofer and is distributed under the
+MIT License. Its full license is included at
+`dist/vendor/json-schema-library/LICENSE.md`.
+
 ## JSON Schema metaschemas
 
 `src/metaschemas/` contains the published JSON Schema metaschema documents for

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAMxF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA8B5B"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAQxF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAwF5B"}

package/dist/adapter.js

@@ -1,12 +1,16 @@
-import { compileSchema, } from 'json-schema-library';
+import { compileSchema, isSchemaNode, } from './vendor/json-schema-library/index.mjs';
 import { detectDialect } from './dialect.js';
 import { loadMetaschemas, referencedDialects } from './metaschemas/index.js';
+import { loadExternalResources } from './resources.js';
+import { materializeLocalPointerAliases } from './local-pointer-aliases.js';
 import { newProjectionCache } from './identity.js';
 import { buildProjection, DEFAULT_LIMITS } from './projection.js';
+import { assertProjectionValidationCoherence } from './projection-validation-coherence.js';
+import { projectSubmissionData, supportsSubmissionProjection } from './submission-projection.js';
 import { withoutUnreachableBranches } from './normalize.js';
 import { DRAFTS } from './bare-maps.js';
 import { fixRootReference } from './root-reference.js';
-import { buildSchemaGraph, rejectSameLocationCycles, cyclicPositions, markPositions } from './schema-graph.js';
+import { buildSchemaGraph, rejectSameLocationCycles, cyclicPositions, markPositions, POSITION } from './schema-graph.js';
 import { pointerResolver } from './instance-pointer.js';
 export async function createJsonSchemaAdapter(schema, config) {
     return createAdapter(schema, config, DEFAULT_LIMITS);
@@ -15,21 +19,68 @@ export async function createAdapter(schema, config, limits) {
     const dialect = detectDialect(schema, {
         defaultDialect: config?.defaultDialect ?? 'draft-07',
     });
+    if (config?.dynamicReferenceProjection === 'local' && dialect === 'draft-07') {
+        throw new TypeError('Local dynamic reference projection requires Draft 2019-09 or Draft 2020-12.');
+    }
     // json-schema-library carries no metaschema documents, so a schema referencing its own fails closed.
-    const referenced = referencedDialects(schema);
-    const remotes = referenced.length > 0 ? await loadMetaschemas(referenced) : undefined;
+    const externalRemotes = await loadExternalResources(schema, dialect, config);
+    const referenced = referencedDialects([schema, ...externalRemotes]);
+    const metaschemas = referenced.length > 0 ? await loadMetaschemas(referenced) : [];
+    const remotes = [...metaschemas, ...externalRemotes];
+    const graph = buildSchemaGraph(schema, dialect, remotes);
+    const referencesByDocument = new Map();
+    for (const target of graph.references.values()) {
+        const hash = target.indexOf('#');
+        if (hash < 0)
+            continue;
+        const prefix = target.slice(0, hash);
+        const pointers = referencesByDocument.get(prefix) ?? [];
+        pointers.push(target.slice(hash));
+        referencesByDocument.set(prefix, pointers);
+    }
     // json-schema-library evaluates some branches the specification never does, so only the projection drops them.
-    const document = withoutUnreachableBranches(schema);
-    const graph = buildSchemaGraph(document, dialect, remotes ?? []);
+    const document = withoutUnreachableBranches(schema, referencesByDocument.get('') ?? []);
+    const projectionRemotes = [
+        ...metaschemas,
+        ...externalRemotes.map((remote) => {
+            const id = remote.$id;
+            const base = typeof id === 'string' ? id.split('#', 1)[0] : '';
+            return withoutUnreachableBranches(remote, referencesByDocument.get(base) ?? []);
+        }),
+    ];
     rejectSameLocationCycles(graph);
-    const marked = markPositions(graph, document, remotes ?? []);
+    const marked = markPositions(graph, document, projectionRemotes);
     const validated = await prepareSchema(schema, dialect, remotes);
-    const projected = await prepareSchema(marked.document, dialect, remotes && marked.remotes);
-    const cache = newProjectionCache(dialect, cyclicPositions(graph), marked.at);
+    const projected = await prepareSchema(marked.document, dialect, marked.remotes);
+    const dynamicReferenceProjection = config?.dynamicReferenceProjection === 'local';
+    if (dynamicReferenceProjection) {
+        const externalResourceIds = new Set(externalRemotes.flatMap((remote) => {
+            const id = remote.$id;
+            return typeof id === 'string' ? [id.split('#', 1)[0]] : [];
+        }));
+        enableLocalDynamicReferenceScopes(validated, dialect, externalResourceIds);
+        enableLocalDynamicReferenceScopes(projected, dialect, externalResourceIds);
+    }
+    assertProjectionValidationCoherence(validated, projected, dialect);
+    const submissionSchema = supportsSubmissionProjection([schema, ...remotes], dialect)
+        ? await prepareSchema(marked.document, dialect, marked.remotes)
+        : undefined;
+    if (dynamicReferenceProjection && submissionSchema) {
+        const externalResourceIds = new Set(externalRemotes.flatMap((remote) => {
+            const id = remote.$id;
+            return typeof id === 'string' ? [id.split('#', 1)[0]] : [];
+        }));
+        enableLocalDynamicReferenceScopes(submissionSchema, dialect, externalResourceIds);
+    }
+    // A schema node can validate differently under different dynamic anchor scopes.
+    const cache = newProjectionCache(dialect, cyclicPositions(graph), marked.at, dynamicReferenceProjection, !dynamicReferenceProjection && !hasOneOf([marked.document, marked.remotes]), graph.retainedPositions);
     return {
-        project(data) {
-            return buildProjection(projected, data, cache, limits);
+        project(data, options) {
+            return buildProjection(projected, data, cache, limits, options);
         },
+        ...(submissionSchema
+            ? { projectSubmission: (data) => projectSubmissionData(validated, submissionSchema, data, dialect) }
+            : {}),
         validate(data) {
             return runValidation(validated, data);
         },
@@ -38,6 +89,386 @@ export async function createAdapter(schema, config, limits) {
         },
     };
 }
+const DYNAMIC_REFERENCE_ANNOTATIONS = new Set([
+    '$anchor', '$comment', '$dynamicAnchor', '$id', '$schema', 'default', 'deprecated', 'description', 'examples',
+    'readOnly', 'title', 'writeOnly', POSITION,
+]);
+const DYNAMIC_REFERENCE_SCOPE_BARRIERS = new Set([
+    'additionalItems', 'additionalProperties', 'contains', 'contentSchema', 'not', 'patternProperties', 'prefixItems',
+    'propertyNames', 'unevaluatedItems', 'unevaluatedProperties',
+]);
+const SCHEMA_MAP_KEYWORDS = new Set([
+    '$defs', 'definitions', 'dependencies', 'dependentSchemas', 'patternProperties', 'properties',
+]);
+const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const SCHEMA_SINGLE_KEYWORDS = new Set([
+    'additionalItems', 'additionalProperties', 'contains', 'contentSchema', 'else', 'if', 'not', 'propertyNames', 'then',
+    'unevaluatedItems', 'unevaluatedProperties',
+]);
+function enableLocalDynamicReferenceScopes(root, dialect, externalResourceIds) {
+    const compiledRoots = [
+        root,
+        ...Object.values(root.context.remotes).filter((remote) => {
+            if (!isSchemaNode(remote) || remote === root || typeof remote.$id !== 'string')
+                return false;
+            return externalResourceIds.has(remote.$id.split('#', 1)[0]);
+        }),
+    ];
+    const referencePolicies = new Map();
+    const recursiveReferencePolicies = new Map();
+    const unclassifiedCompiledReferencePolicies = new Set();
+    const classifiedReferencePolicies = new Set();
+    const activeValidationScope = [];
+    const validatorWrappers = new WeakMap();
+    const wrappedValidators = new WeakSet();
+    let validationDepth = 0;
+    let reductionDepth = 0;
+    for (const compiledRoot of compiledRoots) {
+        const authoredReferencePaths = collectAuthoredReferencePaths(compiledRoot.schema);
+        for (const node of compiledRoot.toSchemaNodes()) {
+            if (node.$id?.startsWith('/')) {
+                throw new TypeError('Local reference projection does not support root-relative resource identifiers.');
+            }
+            if (typeof node.schema !== 'object' || node.schema === null)
+                continue;
+            const schema = node.schema;
+            if (dialect === '2020-12' && '$recursiveRef' in schema) {
+                throw new TypeError('Local dynamic reference projection does not support $recursiveRef.');
+            }
+            const dynamicReference = dialect === '2020-12' && typeof schema.$dynamicRef === 'string';
+            const recursiveReference = dialect === '2019-09' && typeof schema.$recursiveRef === 'string';
+            if (!dynamicReference && !recursiveReference)
+                continue;
+            if (recursiveReference && schema.$recursiveRef !== '#') {
+                throw new TypeError('Local dynamic reference projection only supports the $recursiveRef value "#".');
+            }
+            const keyword = dynamicReference ? '$dynamicRef' : '$recursiveRef';
+            const reference = schema.$dynamicRef ?? schema.$recursiveRef;
+            const policyKey = referencePolicyKey(node, keyword, reference);
+            const authoredPaths = authoredReferencePaths.get(schema);
+            const parsedPath = authoredPaths ? undefined : schemaKeywordPath(compiledRoot, node.schemaLocation);
+            const keywordPaths = authoredPaths ?? (parsedPath ? [parsedPath] : undefined);
+            if (!keywordPaths) {
+                unclassifiedCompiledReferencePolicies.add(policyKey);
+            }
+            else {
+                classifiedReferencePolicies.add(policyKey);
+                for (const keywords of keywordPaths) {
+                    if (!keywords.some((pathKeyword) => pathKeyword === 'properties' || pathKeyword === 'items') ||
+                        keywords.some((pathKeyword) => DYNAMIC_REFERENCE_SCOPE_BARRIERS.has(pathKeyword))) {
+                        throw new TypeError('Local dynamic reference projection does not support references below unsupported applicators or tuple items.');
+                    }
+                }
+            }
+            if (recursiveReference && Object.keys(schema).some((keyword) => keyword !== '$recursiveRef' && keyword !== POSITION)) {
+                throw new TypeError('Local dynamic reference projection does not support siblings beside $recursiveRef.');
+            }
+            if (dynamicReference && Object.keys(schema).some((keyword) => keyword !== '$dynamicRef' && !DYNAMIC_REFERENCE_ANNOTATIONS.has(keyword))) {
+                throw new TypeError('Local dynamic reference projection does not support assertion siblings beside $dynamicRef.');
+            }
+            const staticTarget = node.resolveRef({ path: [] });
+            if (!isSchemaNode(staticTarget)) {
+                throw new TypeError(`Cannot resolve local reference at ${node.schemaLocation}.`);
+            }
+            const targetRoot = staticTarget.context.rootNode;
+            const targetRootId = targetRoot.$id?.split('#', 1)[0];
+            if (targetRoot !== root && (!targetRootId || !externalResourceIds.has(targetRootId))) {
+                throw new TypeError('Local dynamic reference projection does not support external targets unless they were loaded by the configured resource resolver.');
+            }
+            if (dynamicReference) {
+                const anchor = dynamicReferenceAnchor(schema.$dynamicRef);
+                const policy = anchor !== undefined && staticTarget.schema.$dynamicAnchor === anchor
+                    ? anchor
+                    : undefined;
+                referencePolicies.set(referencePolicyKey(node, '$dynamicRef', schema.$dynamicRef), policy);
+            }
+            else {
+                recursiveReferencePolicies.set(referencePolicyKey(node, '$recursiveRef', schema.$recursiveRef), staticTarget.schema.$recursiveAnchor === true);
+            }
+        }
+    }
+    for (const key of unclassifiedCompiledReferencePolicies) {
+        if (!classifiedReferencePolicies.has(key)) {
+            throw new TypeError('Cannot classify a compiled local dynamic reference.');
+        }
+    }
+    const instrumented = new WeakSet();
+    const instrument = (compiledRoot) => {
+        for (const node of compiledRoot.toSchemaNodes()) {
+            if (instrumented.has(node))
+                continue;
+            instrumented.add(node);
+            const schema = node.schema;
+            node.validators = node.validators.map((validator) => {
+                if (wrappedValidators.has(validator))
+                    return validator;
+                const existing = validatorWrappers.get(validator);
+                if (existing)
+                    return existing;
+                const wrapped = ((params) => {
+                    activeValidationScope.push({ pointer: params.pointer, node: params.node });
+                    try {
+                        return validator(params);
+                    }
+                    finally {
+                        activeValidationScope.pop();
+                    }
+                });
+                Object.assign(wrapped, validator);
+                wrappedValidators.add(wrapped);
+                validatorWrappers.set(validator, wrapped);
+                return wrapped;
+            });
+            const validate = node.validate.bind(node);
+            node.validate = ((data, pointer = '#', path = []) => {
+                const outermost = validationDepth === 0;
+                const inheritedLength = activeValidationScope.length;
+                if (outermost)
+                    activeValidationScope.push(...path);
+                validationDepth += 1;
+                try {
+                    return validate(data, pointer, path);
+                }
+                finally {
+                    validationDepth -= 1;
+                    if (outermost)
+                        activeValidationScope.length = inheritedLength;
+                }
+            });
+            const reduceNode = node.reduceNode.bind(node);
+            node.reduceNode = ((data, options = {}) => {
+                const outermost = reductionDepth === 0;
+                const inheritedLength = activeValidationScope.length;
+                if (outermost)
+                    activeValidationScope.push(...(options.path ?? []));
+                if (activeValidationScope[activeValidationScope.length - 1]?.node !== node) {
+                    activeValidationScope.push({ pointer: options.pointer ?? node.evaluationPath, node });
+                }
+                reductionDepth += 1;
+                try {
+                    return reduceNode(data, options);
+                }
+                finally {
+                    reductionDepth -= 1;
+                    activeValidationScope.length = inheritedLength;
+                }
+            });
+            if (dialect === '2020-12' && typeof schema.$dynamicRef === 'string') {
+                const key = referencePolicyKey(node, '$dynamicRef', schema.$dynamicRef);
+                if (!referencePolicies.has(key)) {
+                    throw new TypeError(`Cannot verify compiled local $dynamicRef at ${node.schemaLocation}.`);
+                }
+                const anchor = referencePolicies.get(key);
+                const resolveRef = node.resolveRef.bind(node);
+                node.resolveRef = ({ pointer, path = [] } = {}) => {
+                    if (anchor === undefined) {
+                        const staticPath = [];
+                        const resolved = resolveRef({ pointer, path: staticPath });
+                        if (path !== staticPath)
+                            path.push(...staticPath);
+                        return resolved;
+                    }
+                    const scopedPath = [];
+                    const scope = (validationDepth > 0 || reductionDepth > 0) && activeValidationScope.length > 0
+                        ? activeValidationScope
+                        : path;
+                    for (const entry of scope) {
+                        const anchorNode = entry.node.context.dynamicAnchors[dynamicAnchorUri(entry.node.$id, anchor)];
+                        if (isSchemaNode(anchorNode))
+                            scopedPath.push({ pointer: entry.pointer, node: anchorNode });
+                    }
+                    const inheritedLength = scopedPath.length;
+                    const resolved = resolveRef({ pointer, path: scopedPath });
+                    if (path !== scopedPath)
+                        path.push(...scopedPath.slice(inheritedLength));
+                    return resolved;
+                };
+            }
+            if (dialect === '2019-09' && typeof schema.$recursiveRef === 'string') {
+                const key = referencePolicyKey(node, '$recursiveRef', schema.$recursiveRef);
+                let isRecursive = recursiveReferencePolicies.get(key);
+                if (isRecursive === undefined && !recursiveReferencePolicies.has(key)) {
+                    if (schema.$recursiveRef !== '#') {
+                        throw new TypeError(`Cannot verify compiled local $recursiveRef at ${node.schemaLocation}.`);
+                    }
+                    const staticTarget = node.resolveRef({ path: [] });
+                    const targetRootId = isSchemaNode(staticTarget) ? staticTarget.context.rootNode.$id?.split('#', 1)[0] : undefined;
+                    if (!isSchemaNode(staticTarget) ||
+                        (staticTarget.context.rootNode !== root && (!targetRootId || !externalResourceIds.has(targetRootId)))) {
+                        throw new TypeError(`Cannot verify compiled local $recursiveRef at ${node.schemaLocation}.`);
+                    }
+                    isRecursive = staticTarget.schema.$recursiveAnchor === true;
+                }
+                const resolveRef = node.resolveRef.bind(node);
+                node.resolveRef = ({ pointer, path = [] } = {}) => {
+                    const staticPath = [];
+                    const staticTarget = resolveRef({ pointer, path: staticPath });
+                    if (!isRecursive || !isSchemaNode(staticTarget) || staticTarget.schema.$recursiveAnchor !== true) {
+                        if (path !== staticPath)
+                            path.push(...staticPath);
+                        return staticTarget;
+                    }
+                    const scope = (validationDepth > 0 || reductionDepth > 0) && activeValidationScope.length > 0
+                        ? activeValidationScope
+                        : path;
+                    const outerAnchor = scope.find(({ node: entry }) => entry.schema.$recursiveAnchor === true);
+                    if (outerAnchor) {
+                        const resourceRoot = outerAnchor.node.getNodeRef('#');
+                        if (isSchemaNode(resourceRoot)) {
+                            path.push({ pointer: pointer, node: resourceRoot });
+                            return resourceRoot;
+                        }
+                    }
+                    if (path !== staticPath)
+                        path.push(...staticPath);
+                    return staticTarget;
+                };
+            }
+            const compileSchema = node.compileSchema.bind(node);
+            node.compileSchema = ((schema, evaluationPath, schemaLocation, dynamicId) => {
+                const compiled = compileSchema(schema, evaluationPath, schemaLocation, dynamicId);
+                instrument(compiled);
+                return compiled;
+            });
+        }
+    };
+    for (const compiledRoot of compiledRoots)
+        instrument(compiledRoot);
+}
+function referencePolicyKey(node, keyword, reference) {
+    return `${node.$id ?? ''}\u0000${keyword}\u0000${reference}`;
+}
+function collectAuthoredReferencePaths(schema) {
+    const paths = new WeakMap();
+    const ancestors = new Set();
+    const visit = (value, keywords) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value) || ancestors.has(value))
+            return;
+        ancestors.add(value);
+        const current = value;
+        if (typeof current.$dynamicRef === 'string' || typeof current.$recursiveRef === 'string') {
+            const found = paths.get(value) ?? [];
+            found.push(keywords);
+            paths.set(value, found);
+        }
+        for (const keyword of SCHEMA_MAP_KEYWORDS) {
+            const map = current[keyword];
+            if (typeof map !== 'object' || map === null || Array.isArray(map))
+                continue;
+            for (const child of Object.values(map))
+                visit(child, [...keywords, keyword]);
+        }
+        for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+            const branches = current[keyword];
+            if (Array.isArray(branches)) {
+                for (const child of branches)
+                    visit(child, [...keywords, keyword]);
+            }
+        }
+        for (const keyword of SCHEMA_SINGLE_KEYWORDS) {
+            visit(current[keyword], [...keywords, keyword]);
+        }
+        if (Object.hasOwn(current, 'items')) {
+            const items = current.items;
+            if (Array.isArray(items)) {
+                for (const child of items)
+                    visit(child, [...keywords, 'prefixItems']);
+            }
+            else {
+                visit(items, [...keywords, 'items']);
+            }
+        }
+        ancestors.delete(value);
+    };
+    visit(schema, []);
+    return paths;
+}
+function schemaKeywordPath(root, schemaLocation) {
+    const hashIndex = schemaLocation.indexOf('#');
+    if (hashIndex < 0)
+        return undefined;
+    const fragment = schemaLocation.slice(hashIndex + 1);
+    if (!fragment.startsWith('/'))
+        return [];
+    const segments = fragment.slice(1).split('/');
+    const keywords = [];
+    let current = root.schema;
+    let index = 0;
+    while (index < segments.length) {
+        if (typeof current !== 'object' || current === null || Array.isArray(current))
+            return undefined;
+        const schema = current;
+        const segment = segments[index];
+        if (SCHEMA_MAP_KEYWORDS.has(segment)) {
+            keywords.push(segment);
+            const map = schema[segment];
+            const member = segments[index + 1];
+            if (typeof map !== 'object' || map === null || Array.isArray(map) || member === undefined ||
+                !Object.prototype.hasOwnProperty.call(map, member))
+                return undefined;
+            current = map[member];
+            index += 2;
+            continue;
+        }
+        if (SCHEMA_ARRAY_KEYWORDS.has(segment)) {
+            keywords.push(segment);
+            const array = schema[segment];
+            const itemIndex = Number(segments[index + 1]);
+            if (!Array.isArray(array) || !Number.isInteger(itemIndex) || itemIndex < 0 || itemIndex >= array.length) {
+                return undefined;
+            }
+            current = array[itemIndex];
+            index += 2;
+            continue;
+        }
+        if (segment === 'items') {
+            const items = schema.items;
+            if (Array.isArray(items)) {
+                keywords.push('prefixItems');
+                const itemIndex = Number(segments[index + 1]);
+                if (!Number.isInteger(itemIndex) || itemIndex < 0 || itemIndex >= items.length)
+                    return undefined;
+                current = items[itemIndex];
+                index += 2;
+            }
+            else {
+                keywords.push(segment);
+                if (!(segment in schema))
+                    return undefined;
+                current = items;
+                index += 1;
+            }
+            continue;
+        }
+        if (SCHEMA_SINGLE_KEYWORDS.has(segment)) {
+            keywords.push(segment);
+            if (!(segment in schema))
+                return undefined;
+            current = schema[segment];
+            index += 1;
+            continue;
+        }
+        return undefined;
+    }
+    return keywords;
+}
+function dynamicAnchorUri(resourceId, anchor) {
+    const currentId = resourceId ?? '#';
+    return `${currentId.replace(/#.*$/, '')}#${anchor}`;
+}
+function dynamicReferenceAnchor(reference) {
+    const hash = reference.indexOf('#');
+    if (hash < 0)
+        return undefined;
+    let fragment;
+    try {
+        fragment = decodeURIComponent(reference.slice(hash + 1));
+    }
+    catch {
+        throw new TypeError(`Local dynamic reference projection cannot decode anchor in ${reference}.`);
+    }
+    return fragment === '' || fragment.startsWith('/') ? undefined : fragment;
+}
 // json-schema-library's `draft` compile option uses "draft-2019-09"/"draft-2020-12" rather
 // than this package's "2019-09"/"2020-12" Dialect values.
 function toDraftOption(dialect) {
@@ -53,15 +484,35 @@ async function prepareSchema(schema, dialect, remotes) {
     // annotation unless the format-assertion vocabulary is declared, so asserting it
     // is a deviation rather than a stricter setting.
     const formatAssertion = dialect === 'draft-07' ? undefined : false;
-    const root = compileSchema(schema, {
+    const root = compileSchema(materializeLocalPointerAliases(schema, dialect), {
         drafts: DRAFTS,
         draft: toDraftOption(dialect),
         formatAssertion,
-        remotes,
+        remotes: remotes?.map((remote) => materializeLocalPointerAliases(remote, dialect, true)),
     });
     fixRootReference(root, dialect);
     return root;
 }
+function hasOneOf(value, visited = new WeakSet()) {
+    if (typeof value !== 'object' || value === null || visited.has(value))
+        return false;
+    visited.add(value);
+    let descriptors;
+    try {
+        descriptors = Object.getOwnPropertyDescriptors(value);
+    }
+    catch {
+        return true;
+    }
+    const properties = Object.values(descriptors);
+    if (properties.some((descriptor) => !('value' in descriptor)))
+        return true;
+    const oneOf = descriptors.oneOf;
+    if (oneOf && Array.isArray(oneOf.value) && oneOf.value.length > 0) {
+        return true;
+    }
+    return properties.some((descriptor) => hasOneOf(descriptor.value, visited));
+}
 // jsl error codes are kebab-case ("min-length-error"); ValidationError.keyword is expected
 // to be the JSON Schema keyword itself ("minLength"). Unrecognized codes fall back to a
 // best-effort camelCase conversion of the code with any trailing "-error"/"-warning" removed.