@apidevtools/json-schema-ref-parser 15.3.1 → 15.3.2

package/dist/lib/bundle.js

@@ -1,6 +1,7 @@
 import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 /**
  * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  * only has *internal* references, not any *external* references.
@@ -13,7 +14,7 @@ function bundle(parser, options) {
     // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
     // Build an inventory of all $ref pointers in the JSON Schema
     const inventory = [];
-    crawl(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
+    crawl(parser, "schema", parser.$refs._root$Ref.path + "#", parser.$refs._root$Ref.path, parser.$refs._root$Ref.dynamicIdScope, "#", 0, inventory, parser.$refs, options);
     // Get the root schema's $id (if any) for qualifying refs inside sub-schemas with their own $id
     const rootId = parser.schema && typeof parser.schema === "object" && "$id" in parser.schema
         ? parser.schema.$id
@@ -38,13 +39,14 @@ function bundle(parser, options) {
  * @param $refs
  * @param options
  */
-function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs, options) {
+function crawl(parent, key, path, scopeBase, dynamicIdScope, pathFromRoot, indirections, inventory, $refs, options) {
     const obj = key === null ? parent : parent[key];
     const bundleOptions = (options.bundle || {});
     const isExcludedPath = bundleOptions.excludedPathMatcher || (() => false);
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
+        const currentScopeBase = dynamicIdScope ? getSchemaBasePath(scopeBase, obj) : scopeBase;
         if ($Ref.isAllowed$Ref(obj)) {
-            inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
+            inventory$Ref(parent, key, path, currentScopeBase, dynamicIdScope, pathFromRoot, indirections, inventory, $refs, options);
         }
         else {
             // Crawl the object in a specific order that's optimized for bundling.
@@ -70,10 +72,11 @@ function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs,
                 const keyPathFromRoot = Pointer.join(pathFromRoot, key);
                 const value = obj[key];
                 if ($Ref.isAllowed$Ref(value)) {
-                    inventory$Ref(obj, key, path, keyPathFromRoot, indirections, inventory, $refs, options);
+                    const valueScopeBase = dynamicIdScope ? getSchemaBasePath(currentScopeBase, value) : currentScopeBase;
+                    inventory$Ref(obj, key, keyPath, valueScopeBase, dynamicIdScope, keyPathFromRoot, indirections, inventory, $refs, options);
                 }
                 else {
-                    crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
+                    crawl(obj, key, keyPath, currentScopeBase, dynamicIdScope, keyPathFromRoot, indirections, inventory, $refs, options);
                 }
                 // We need to ensure that we have an object to work with here because we may be crawling
                 // an `examples` schema and `value` may be nullish.
@@ -99,9 +102,9 @@ function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs,
  * @param $refs
  * @param options
  */
-function inventory$Ref($refParent, $refKey, path, pathFromRoot, indirections, inventory, $refs, options) {
+function inventory$Ref($refParent, $refKey, path, scopeBase, dynamicIdScope, pathFromRoot, indirections, inventory, $refs, options) {
     const $ref = $refKey === null ? $refParent : $refParent[$refKey];
-    const $refPath = url.resolve(path, $ref.$ref);
+    const $refPath = url.resolve(dynamicIdScope ? scopeBase : path, $ref.$ref);
     const pointer = $refs._resolve($refPath, pathFromRoot, options);
     if (pointer === null) {
         return;
@@ -110,7 +113,7 @@ function inventory$Ref($refParent, $refKey, path, pathFromRoot, indirections, in
     const depth = parsed.length;
     const file = url.stripHash(pointer.path);
     const hash = url.getHash(pointer.path);
-    const external = file !== $refs._root$Ref.path;
+    const external = file !== $refs._root$Ref.path && !$refs._aliases[file];
     const extended = $Ref.isExtended$Ref($ref);
     indirections += pointer.indirections;
     const existingEntry = findInInventory(inventory, $refParent, $refKey);
@@ -139,7 +142,7 @@ function inventory$Ref($refParent, $refKey, path, pathFromRoot, indirections, in
     });
     // Recursively crawl the resolved value
     if (!existingEntry || external) {
-        crawl(pointer.value, null, pointer.path, pathFromRoot, indirections + 1, inventory, $refs, options);
+        crawl(pointer.value, null, pointer.path, pointer.$ref.path, pointer.$ref.dynamicIdScope, pathFromRoot, indirections + 1, inventory, $refs, options);
     }
 }
 /**

package/dist/lib/dereference.js

@@ -1,6 +1,7 @@
 import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 import { TimeoutError } from "./util/errors.js";
 export default dereference;
 /**
@@ -13,7 +14,7 @@ export default dereference;
 function dereference(parser, options) {
     const start = Date.now();
     // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
-    const dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, "#", new Set(), new Set(), new Map(), parser.$refs, options, start, 0);
+    const dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, parser.$refs._root$Ref.path, parser.$refs._root$Ref.dynamicIdScope, "#", new Set(), new Set(), new Map(), parser.$refs, options, start, 0);
     parser.$refs.circular = dereferenced.circular;
     parser.schema = dereferenced.value;
 }
@@ -32,7 +33,7 @@ function dereference(parser, options) {
  * @param depth - The current recursion depth
  * @returns
  */
-function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
+function crawl(obj, path, scopeBase, dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
     let dereferenced;
     const result = {
         value: obj,
@@ -51,8 +52,9 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
         if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
             parents.add(obj);
             processedObjects.add(obj);
+            const currentScopeBase = dynamicIdScope ? getSchemaBasePath(scopeBase, obj) : scopeBase;
             if ($Ref.isAllowed$Ref(obj, options)) {
-                dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
+                dereferenced = dereference$Ref(obj, path, currentScopeBase, dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
                 result.circular = dereferenced.circular;
                 result.value = dereferenced.value;
             }
@@ -67,7 +69,8 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
                     const value = obj[key];
                     let circular;
                     if ($Ref.isAllowed$Ref(value, options)) {
-                        dereferenced = dereference$Ref(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
+                        const valueScopeBase = dynamicIdScope ? getSchemaBasePath(currentScopeBase, value) : currentScopeBase;
+                        dereferenced = dereference$Ref(value, keyPath, valueScopeBase, dynamicIdScope, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
                         circular = dereferenced.circular;
                         // Avoid pointless mutations; breaks frozen objects to no profit
                         if (obj[key] !== dereferenced.value) {
@@ -104,7 +107,7 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
                     }
                     else {
                         if (!parents.has(value)) {
-                            dereferenced = crawl(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
+                            dereferenced = crawl(value, keyPath, currentScopeBase, dynamicIdScope, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
                             circular = dereferenced.circular;
                             // Avoid pointless mutations; breaks frozen objects to no profit
                             if (obj[key] !== dereferenced.value) {
@@ -137,10 +140,11 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
  * @param options
  * @returns
  */
-function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
+function dereference$Ref($ref, path, scopeBase, dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
     const isExternalRef = $Ref.isExternal$Ref($ref);
     const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
-    const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
+    const resolutionBase = shouldResolveOnCwd ? url.cwd() : dynamicIdScope ? scopeBase : path;
+    const $refPath = url.resolve(resolutionBase, $ref.$ref);
     const cache = dereferencedCache.get($refPath);
     if (cache) {
         // If the object we found is circular we can immediately return it because it would have been
@@ -210,7 +214,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
     // Crawl the dereferenced value (unless it's circular)
     if (!circular) {
         // Determine if the dereferenced value is circular
-        const dereferenced = crawl(dereferencedValue, pointer.path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
+        const dereferenced = crawl(dereferencedValue, pointer.path, pointer.$ref.path, pointer.$ref.dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
         circular = dereferenced.circular;
         dereferencedValue = dereferenced.value;
     }

package/dist/lib/index.js

@@ -9,6 +9,7 @@ import FileResolver from "./resolvers/file.js";
 import HTTPResolver from "./resolvers/http.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, UnmatchedResolverError, isHandledError, JSONParserErrorGroup, } from "./util/errors.js";
 import maybe from "./util/maybe.js";
+import { registerSchemaResources, usesDynamicIdScope } from "./util/schema-resources.js";
 import { getJsonSchemaRefParserDefaultOptions } from "./options.js";
 import { isUnsafeUrl } from "./util/url.js";
 /**
@@ -68,6 +69,8 @@ export class $RefParser {
             const $ref = this.$refs._add(args.path);
             $ref.value = args.schema;
             $ref.pathType = pathType;
+            $ref.dynamicIdScope = usesDynamicIdScope($ref.value);
+            registerSchemaResources(this.$refs, $ref.path, $ref.value, $ref.pathType, $ref.dynamicIdScope);
             promise = Promise.resolve(args.schema);
         }
         else {

package/dist/lib/parse.d.ts

@@ -1,8 +1,13 @@
 import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types/index.js";
+interface ParseTarget {
+    url: string;
+    reference?: string;
+    baseUrl?: string;
+}
 /**
  * Reads and parses the specified file path or URL.
  */
-declare function parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(path: string, $refs: $Refs<S, O>, options: O): Promise<string | Buffer<ArrayBufferLike> | S | undefined>;
+declare function parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(target: string | ParseTarget, $refs: $Refs<S, O>, options: O): Promise<string | Buffer<ArrayBufferLike> | S | undefined>;
 export default parse;

package/dist/lib/parse.js

@@ -1,10 +1,14 @@
 import * as url from "./util/url.js";
+import { registerSchemaResources, usesDynamicIdScope } from "./util/schema-resources.js";
 import { filter, all, sort, run } from "./util/plugins.js";
 import { ResolverError, ParserError, UnmatchedParserError, UnmatchedResolverError, isHandledError, } from "./util/errors.js";
 /**
  * Reads and parses the specified file path or URL.
  */
-async function parse(path, $refs, options) {
+async function parse(target, $refs, options) {
+    let path = typeof target === "string" ? target : target.url;
+    const baseUrl = typeof target === "string" ? undefined : target.baseUrl;
+    let reference = typeof target === "string" ? undefined : target.reference;
     // Remove the URL fragment, if any
     const hashIndex = path.indexOf("#");
     let hash = "";
@@ -13,6 +17,12 @@ async function parse(path, $refs, options) {
         // Remove the URL fragment, if any
         path = path.substring(0, hashIndex);
     }
+    if (reference) {
+        const referenceHashIndex = reference.indexOf("#");
+        if (referenceHashIndex >= 0) {
+            reference = reference.substring(0, referenceHashIndex);
+        }
+    }
     // Add a new $Ref for this file, even though we don't have the value yet.
     // This ensures that we don't simultaneously read & parse the same file multiple times
     const $ref = $refs._add(path);
@@ -21,6 +31,8 @@ async function parse(path, $refs, options) {
         url: path,
         hash,
         extension: url.getExtension(path),
+        ...(reference !== undefined ? { reference } : {}),
+        ...(baseUrl !== undefined ? { baseUrl } : {}),
     };
     // Read the file and then parse the data
     try {
@@ -29,6 +41,8 @@ async function parse(path, $refs, options) {
         file.data = resolver.result;
         const parser = await parseFile(file, options, $refs);
         $ref.value = parser.result;
+        $ref.dynamicIdScope = usesDynamicIdScope($ref.value);
+        registerSchemaResources($refs, $ref.path, $ref.value, $ref.pathType, $ref.dynamicIdScope);
         return parser.result;
     }
     catch (err) {

package/dist/lib/pointer.d.ts

@@ -25,6 +25,10 @@ declare class Pointer<S extends object = JSONSchema, O extends ParserOptions<S>
      * The original path or URL, used for error messages.
      */
     originalPath: string;
+    /**
+     * The current base URI used to resolve nested $ref pointers while walking this pointer.
+     */
+    scopeBase: string;
     /**
      * The value of the JSON pointer.
      * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).

package/dist/lib/pointer.js

@@ -1,6 +1,7 @@
 import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 export const nullSymbol = Symbol("null");
 const slashes = /\//g;
 const tildes = /~/g;
@@ -28,6 +29,10 @@ class Pointer {
      * The original path or URL, used for error messages.
      */
     originalPath;
+    /**
+     * The current base URI used to resolve nested $ref pointers while walking this pointer.
+     */
+    scopeBase;
     /**
      * The value of the JSON pointer.
      * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
@@ -46,6 +51,7 @@ class Pointer {
         this.$ref = $ref;
         this.path = path;
         this.originalPath = friendlyPath || path;
+        this.scopeBase = $ref.path || url.stripHash(path);
         this.value = undefined;
         this.circular = false;
         this.indirections = 0;
@@ -68,6 +74,9 @@ class Pointer {
         const found = [];
         // Crawl the object, one token at a time
         this.value = unwrapOrThrow(obj);
+        if (this.$ref.dynamicIdScope) {
+            this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+        }
         for (let i = 0; i < tokens.length; i++) {
             // During token walking, if the current value is an extended $ref (has sibling keys
             // alongside $ref, as allowed by JSON Schema 2019-09+), and resolveIf$Ref marks it
@@ -123,9 +132,13 @@ class Pointer {
                 this.value = this.value[token];
             }
             found.push(token);
+            if (this.$ref.dynamicIdScope) {
+                this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+            }
         }
         // Resolve the final value
-        if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
+        const finalResolutionBase = this.$ref.dynamicIdScope ? this.scopeBase : this.path;
+        if (!this.value || (this.value.$ref && url.resolve(finalResolutionBase, this.value.$ref) !== pathFromRoot)) {
             resolveIf$Ref(this, options, pathFromRoot);
         }
         return this;
@@ -150,6 +163,9 @@ class Pointer {
         }
         // Crawl the object, one token at a time
         this.value = unwrapOrThrow(obj);
+        if (this.$ref.dynamicIdScope) {
+            this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+        }
         for (let i = 0; i < tokens.length - 1; i++) {
             resolveIf$Ref(this, options);
             token = tokens[i];
@@ -161,6 +177,9 @@ class Pointer {
                 // The token doesn't exist, so create it
                 this.value = setValue(this, token, {});
             }
+            if (this.$ref.dynamicIdScope) {
+                this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+            }
         }
         // Set the value of the final token
         resolveIf$Ref(this, options);
@@ -238,7 +257,8 @@ class Pointer {
 function resolveIf$Ref(pointer, options, pathFromRoot) {
     // Is the value a JSON reference? (and allowed?)
     if ($Ref.isAllowed$Ref(pointer.value, options)) {
-        const $refPath = url.resolve(pointer.path, pointer.value.$ref);
+        const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
+        const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
         if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
             // The value is a reference to itself, so there's nothing to do.
             pointer.circular = true;
@@ -253,6 +273,9 @@ function resolveIf$Ref(pointer, options, pathFromRoot) {
                 // This JSON reference "extends" the resolved value, rather than simply pointing to it.
                 // So the resolved path does NOT change.  Just the value does.
                 pointer.value = $Ref.dereference(pointer.value, resolved.value, options);
+                if (pointer.$ref.dynamicIdScope) {
+                    pointer.scopeBase = getSchemaBasePath(pointer.scopeBase, pointer.value);
+                }
                 return false;
             }
             else {
@@ -260,6 +283,9 @@ function resolveIf$Ref(pointer, options, pathFromRoot) {
                 pointer.$ref = resolved.$ref;
                 pointer.path = resolved.path;
                 pointer.value = resolved.value;
+                pointer.scopeBase = pointer.$ref.dynamicIdScope
+                    ? getSchemaBasePath(pointer.$ref.path, pointer.value)
+                    : pointer.$ref.path;
             }
             return true;
         }

package/dist/lib/ref.d.ts

@@ -39,6 +39,10 @@ declare class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = P
      * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
      */
     pathType: string | unknown;
+    /**
+     * Whether this document/resource should use JSON Schema 2019-09+ nested $id scope semantics.
+     */
+    dynamicIdScope: boolean;
     /**
      * List of all errors. Undefined if no errors.
      */

package/dist/lib/ref.js

@@ -35,6 +35,10 @@ class $Ref {
      * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
      */
     pathType;
+    /**
+     * Whether this document/resource should use JSON Schema 2019-09+ nested $id scope semantics.
+     */
+    dynamicIdScope = false;
     /**
      * List of all errors. Undefined if no errors.
      */

package/dist/lib/refs.d.ts

@@ -79,6 +79,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
      * @param path  - The file path or URL of the referenced file
      */
     _add(path: string): $Ref<S, O>;
+    _addAlias(path: string, value: S, pathType?: string | unknown, dynamicIdScope?: boolean): $Ref<S, O>;
     /**
      * Resolves the given JSON reference.
      *
@@ -96,6 +97,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
      * @protected
      */
     _$refs: $RefsMap<S, O>;
+    _aliases: $RefsMap<S, O>;
     /**
      * The {@link $Ref} object that is the root of the JSON schema.
      *
@@ -123,5 +125,6 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
      * @returns {object}
      */
     toJSON: (...types: (string | string[])[]) => S;
+    private _getRef;
 }
 export {};

package/dist/lib/refs.js

@@ -84,10 +84,9 @@ export default class $Refs {
      */
     set(path, value) {
         const absPath = url.resolve(this._root$Ref.path, path);
-        const withoutHash = url.stripHash(absPath);
-        const $ref = this._$refs[withoutHash];
+        const $ref = this._getRef(absPath);
         if (!$ref) {
-            throw new Error(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+            throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
         }
         $ref.set(absPath, value);
     }
@@ -100,8 +99,7 @@ export default class $Refs {
      */
     _get$Ref(path) {
         path = url.resolve(this._root$Ref.path, path);
-        const withoutHash = url.stripHash(path);
-        return this._$refs[withoutHash];
+        return this._getRef(path);
     }
     /**
      * Creates a new {@link $Ref} object and adds it to this {@link $Refs} object.
@@ -116,6 +114,19 @@ export default class $Refs {
         this._root$Ref = this._root$Ref || $ref;
         return $ref;
     }
+    _addAlias(path, value, pathType, dynamicIdScope = false) {
+        const withoutHash = url.stripHash(path);
+        if (!withoutHash || this._$refs[withoutHash] || this._aliases[withoutHash]) {
+            return this._$refs[withoutHash] || this._aliases[withoutHash];
+        }
+        const $ref = new $Ref(this);
+        $ref.path = withoutHash;
+        $ref.pathType = pathType;
+        $ref.value = value;
+        $ref.dynamicIdScope = dynamicIdScope;
+        this._aliases[withoutHash] = $ref;
+        return $ref;
+    }
     /**
      * Resolves the given JSON reference.
      *
@@ -127,10 +138,9 @@ export default class $Refs {
      */
     _resolve(path, pathFromRoot, options) {
         const absPath = url.resolve(this._root$Ref.path, path);
-        const withoutHash = url.stripHash(absPath);
-        const $ref = this._$refs[withoutHash];
+        const $ref = this._getRef(absPath);
         if (!$ref) {
-            throw new Error(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+            throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
         }
         return $ref.resolve(absPath, options, path, pathFromRoot);
     }
@@ -141,6 +151,7 @@ export default class $Refs {
      * @protected
      */
     _$refs = {};
+    _aliases = {};
     /**
      * The {@link $Ref} object that is the root of the JSON schema.
      *
@@ -156,6 +167,7 @@ export default class $Refs {
          */
         this.circular = false;
         this._$refs = {};
+        this._aliases = {};
         // @ts-ignore
         this._root$Ref = null;
     }
@@ -178,6 +190,10 @@ export default class $Refs {
      * @returns {object}
      */
     toJSON = this.values;
+    _getRef(path) {
+        const withoutHash = url.stripHash(path);
+        return this._$refs[withoutHash] || this._aliases[withoutHash];
+    }
 }
 /**
  * Returns the encoded and decoded paths keys of the given object.

package/dist/lib/resolve-external.js

@@ -3,6 +3,7 @@ import Pointer from "./pointer.js";
 import parse from "./parse.js";
 import * as url from "./util/url.js";
 import { isHandledError } from "./util/errors.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 /**
  * Crawls the JSON schema, finds all external JSON references, and resolves their values.
  * This method does not mutate the JSON schema. The resolved values are added to {@link $RefParser#$refs}.
@@ -20,7 +21,7 @@ function resolveExternal(parser, options) {
     }
     try {
         // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
-        const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
+        const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs._root$Ref.path, parser.$refs._root$Ref.dynamicIdScope, parser.$refs, options);
         return Promise.all(promises);
     }
     catch (e) {
@@ -43,19 +44,21 @@ function resolveExternal(parser, options) {
  * If any of the JSON references point to files that contain additional JSON references,
  * then the corresponding promise will internally reference an array of promises.
  */
-function crawl(obj, path, $refs, options, seen, external) {
+function crawl(obj, path, scopeBase, dynamicIdScope, $refs, options, seen, external) {
     seen ||= new Set();
     let promises = [];
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
         seen.add(obj); // Track previously seen objects to avoid infinite recursion
+        const currentScopeBase = dynamicIdScope ? getSchemaBasePath(scopeBase, obj) : scopeBase;
         if ($Ref.isExternal$Ref(obj)) {
-            promises.push(resolve$Ref(obj, path, $refs, options));
+            promises.push(resolve$Ref(obj, path, currentScopeBase, dynamicIdScope, $refs, options));
         }
         const keys = Object.keys(obj);
         for (const key of keys) {
             const keyPath = Pointer.join(path, key);
             const value = obj[key];
-            promises = promises.concat(crawl(value, keyPath, $refs, options, seen, external));
+            const childScopeBase = dynamicIdScope && $Ref.isExternal$Ref(value) ? getSchemaBasePath(currentScopeBase, value) : currentScopeBase;
+            promises = promises.concat(crawl(value, keyPath, childScopeBase, dynamicIdScope, $refs, options, seen, external));
         }
     }
     return promises;
@@ -72,23 +75,33 @@ function crawl(obj, path, $refs, options, seen, external) {
  * The promise resolves once all JSON references in the object have been resolved,
  * including nested references that are contained in externally-referenced files.
  */
-async function resolve$Ref($ref, path, $refs, options) {
+async function resolve$Ref($ref, path, scopeBase, dynamicIdScope, $refs, options) {
     const shouldResolveOnCwd = options.dereference?.externalReferenceResolution === "root";
-    const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
+    const resolutionBase = shouldResolveOnCwd ? url.cwd() : dynamicIdScope ? scopeBase : path;
+    const resolvedPath = url.resolve(resolutionBase, $ref.$ref);
     const withoutHash = url.stripHash(resolvedPath);
     // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
     // Do we already have this $ref?
-    const ref = $refs._$refs[withoutHash];
+    const ref = $refs._get$Ref(withoutHash);
     if (ref) {
         // We've already parsed this $ref, so use the existing value
         return Promise.resolve(ref.value);
     }
     // Parse the $referenced file/url
     try {
-        const result = await parse(resolvedPath, $refs, options);
+        const reference = $ref.$ref;
+        const parseTarget = {
+            url: resolvedPath,
+            baseUrl: resolutionBase,
+        };
+        if (typeof reference === "string") {
+            parseTarget.reference = reference;
+        }
+        const result = await parse(parseTarget, $refs, options);
         // Crawl the parsed value
         // console.log('Resolving $ref pointers in %s', withoutHash);
-        const promises = crawl(result, withoutHash + "#", $refs, options, new Set(), true);
+        const parsedRef = $refs._get$Ref(withoutHash);
+        const promises = crawl(result, withoutHash + "#", withoutHash, parsedRef?.dynamicIdScope ?? false, $refs, options, new Set(), true);
         return Promise.all(promises);
     }
     catch (err) {

package/dist/lib/types/index.d.ts

@@ -103,6 +103,17 @@ export interface FileInfo {
      * The full URL of the file. This could be any type of URL, including "http://", "https://", "file://", "ftp://", "mongodb://", or even a local filesystem path (when running in Node.js).
      */
     url: string;
+    /**
+     * The unresolved `$ref` value exactly as it appeared in the parent schema, without the hash.
+     * This is useful for custom resolvers that need to preserve relative reference semantics instead
+     * of relying on the already-resolved `url`.
+     */
+    reference?: string;
+    /**
+     * The URL that `reference` was resolved against to produce `url`.
+     * This may include a JSON Pointer fragment when the reference originated from a nested location.
+     */
+    baseUrl?: string;
     /**
      * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
      */

package/dist/lib/util/schema-resources.d.ts

@@ -0,0 +1,6 @@
+import type { ParserOptions } from "../options.js";
+import type { JSONSchema } from "../index.js";
+import type $Refs from "../refs.js";
+export declare function getSchemaBasePath(basePath: string, value: unknown): string;
+export declare function usesDynamicIdScope(value: unknown): boolean;
+export declare function registerSchemaResources<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>($refs: $Refs<S, O>, basePath: string, value: unknown, pathType?: string | unknown, dynamicIdScope?: boolean): void;

package/dist/lib/util/schema-resources.js

@@ -0,0 +1,47 @@
+import * as url from "./url.js";
+export function getSchemaBasePath(basePath, value) {
+    const schemaId = getSchemaId(value);
+    return schemaId ? url.resolve(basePath, schemaId) : basePath;
+}
+export function usesDynamicIdScope(value) {
+    if (!value || typeof value !== "object" || ArrayBuffer.isView(value)) {
+        return false;
+    }
+    const schema = value.$schema;
+    if (typeof schema === "string" &&
+        (schema.includes("draft/2019-09/") || schema.includes("draft/2020-12/") || schema.includes("oas/3.1/"))) {
+        return true;
+    }
+    const openapi = value.openapi;
+    return typeof openapi === "string" && /^3\.1(?:\.|$)/.test(openapi);
+}
+export function registerSchemaResources($refs, basePath, value, pathType, dynamicIdScope = false) {
+    if (!dynamicIdScope) {
+        return;
+    }
+    const seen = new Set();
+    const visit = (node, scopeBase) => {
+        if (!node || typeof node !== "object" || ArrayBuffer.isView(node) || seen.has(node)) {
+            return;
+        }
+        seen.add(node);
+        const nextScopeBase = getSchemaBasePath(scopeBase, node);
+        if (nextScopeBase !== scopeBase) {
+            $refs._addAlias(nextScopeBase, node, pathType, dynamicIdScope);
+        }
+        for (const key of Object.keys(node)) {
+            visit(node[key], nextScopeBase);
+        }
+    };
+    visit(value, basePath);
+}
+function getSchemaId(value) {
+    if (value &&
+        typeof value === "object" &&
+        "$id" in value &&
+        typeof value.$id === "string" &&
+        value.$id.length > 0) {
+        return value.$id;
+    }
+    return undefined;
+}