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

package/lib/bundle.ts

@@ -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 type $Refs from "./refs.js";
 import type $RefParser from "./index.js";
 import type { ParserOptions } from "./index.js";
@@ -37,7 +38,18 @@ function bundle<S extends object = JSONSchema, O extends ParserOptions<S> = Pars
 
   // Build an inventory of all $ref pointers in the JSON Schema
   const inventory: InventoryEntry[] = [];
-  crawl<S, O>(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
+  crawl<S, O>(
+    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 =
@@ -71,6 +83,8 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   parent: object | $RefParser<S, O>,
   key: string | null,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   pathFromRoot: string,
   indirections: number,
   inventory: InventoryEntry[],
@@ -82,8 +96,9 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   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.
       // This is important because it determines how `pathFromRoot` gets built,
@@ -108,9 +123,21 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
         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
@@ -142,6 +169,8 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   $refParent: any,
   $refKey: string | null,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   pathFromRoot: string,
   indirections: number,
   inventory: InventoryEntry[],
@@ -149,7 +178,7 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   options: O,
 ) {
   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;
@@ -158,7 +187,7 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   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;
 
@@ -189,7 +218,18 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
 
   // 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/lib/dereference.ts

@@ -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 type $Refs from "./refs.js";
 import type { DereferenceOptions, ParserOptions } from "./options.js";
 import { type $RefParser, type JSONSchema } from "./index.js";
@@ -24,6 +25,8 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
   const dereferenced = crawl<S, O>(
     parser.schema,
     parser.$refs._root$Ref.path!,
+    parser.$refs._root$Ref.path!,
+    parser.$refs._root$Ref.dynamicIdScope,
     "#",
     new Set(),
     new Set(),
@@ -55,6 +58,8 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
 function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   obj: any,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   pathFromRoot: string,
   parents: Set<any>,
   processedObjects: Set<any>,
@@ -87,11 +92,14 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
     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,
+          currentScopeBase,
+          dynamicIdScope,
           pathFromRoot,
           parents,
           processedObjects,
@@ -118,9 +126,12 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
           let circular;
 
           if ($Ref.isAllowed$Ref(value, options)) {
+            const valueScopeBase = dynamicIdScope ? getSchemaBasePath(currentScopeBase, value) : currentScopeBase;
             dereferenced = dereference$Ref(
               value,
               keyPath,
+              valueScopeBase,
+              dynamicIdScope,
               keyPathFromRoot,
               parents,
               processedObjects,
@@ -172,6 +183,8 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
               dereferenced = crawl(
                 value,
                 keyPath,
+                currentScopeBase,
+                dynamicIdScope,
                 keyPathFromRoot,
                 parents,
                 processedObjects,
@@ -219,6 +232,8 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
 function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   $ref: any,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   pathFromRoot: string,
   parents: Set<any>,
   processedObjects: any,
@@ -230,7 +245,8 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
 ) {
   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);
 
@@ -310,6 +326,8 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
     const dereferenced = crawl(
       dereferencedValue,
       pointer.path,
+      pointer.$ref.path!,
+      pointer.$ref.dynamicIdScope,
       pathFromRoot,
       parents,
       processedObjects,

package/lib/index.ts

@@ -19,6 +19,7 @@ import {
   JSONParserErrorGroup,
 } from "./util/errors.js";
 import maybe from "./util/maybe.js";
+import { registerSchemaResources, usesDynamicIdScope } from "./util/schema-resources.js";
 import type { ParserOptions } from "./options.js";
 import { getJsonSchemaRefParserDefaultOptions } from "./options.js";
 import type {
@@ -115,6 +116,8 @@ export class $RefParser<S extends object = JSONSchema, O extends ParserOptions<S
       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 {
       // Parse the schema file/url

package/lib/parse.ts

@@ -1,4 +1,5 @@
 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,
@@ -11,14 +12,24 @@ import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
 import type { FileInfo, JSONSchema } from "./types/index.js";
 
+interface ParseTarget {
+  url: string;
+  reference?: string;
+  baseUrl?: string;
+}
+
 /**
  * Reads and parses the specified file path or URL.
  */
 async function parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-  path: string,
+  target: string | ParseTarget,
   $refs: $Refs<S, O>,
   options: O,
 ) {
+  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 = "";
@@ -27,6 +38,12 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
     // 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
@@ -37,6 +54,8 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
     url: path,
     hash,
     extension: url.getExtension(path),
+    ...(reference !== undefined ? { reference } : {}),
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
   } as FileInfo;
 
   // Read the file and then parse the data
@@ -47,6 +66,8 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
 
     const parser = await parseFile<S, O>(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/lib/pointer.ts

@@ -3,6 +3,7 @@ import type { ParserOptions } from "./options.js";
 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";
 import type { JSONSchema } from "./index.js";
 import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
 
@@ -38,6 +39,11 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    */
   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).
@@ -61,6 +67,8 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     this.originalPath = friendlyPath || path;
 
+    this.scopeBase = $ref.path || url.stripHash(path);
+
     this.value = undefined;
 
     this.circular = false;
@@ -87,6 +95,9 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // 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
@@ -149,10 +160,14 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
       }
 
       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);
     }
 
@@ -181,6 +196,9 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // 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);
@@ -193,6 +211,10 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         // 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
@@ -287,7 +309,8 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   // 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.
@@ -304,12 +327,18 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
         // 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 {
         // Resolve the reference
         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/lib/ref.ts

@@ -47,6 +47,11 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    */
   pathType: string | unknown;
 
+  /**
+   * 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/lib/refs.ts

@@ -95,11 +95,10 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   set(path: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
     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);
@@ -113,8 +112,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _get$Ref(path: string) {
     path = url.resolve(this._root$Ref.path!, path);
-    const withoutHash = url.stripHash(path);
-    return this._$refs[withoutHash];
+    return this._getRef(path);
   }
 
   /**
@@ -134,6 +132,23 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
     return $ref;
   }
 
+  _addAlias(path: string, value: S, pathType?: string | unknown, 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<S, O>(this);
+    $ref.path = withoutHash;
+    $ref.pathType = pathType;
+    $ref.value = value;
+    $ref.dynamicIdScope = dynamicIdScope;
+
+    this._aliases[withoutHash] = $ref;
+    return $ref;
+  }
+
   /**
    * Resolves the given JSON reference.
    *
@@ -145,11 +160,10 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _resolve(path: string, pathFromRoot: string, options?: O) {
     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);
@@ -163,6 +177,8 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _$refs: $RefsMap<S, O> = {};
 
+  _aliases: $RefsMap<S, O> = {};
+
   /**
    * The {@link $Ref} object that is the root of the JSON schema.
    *
@@ -180,6 +196,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
     this.circular = false;
 
     this._$refs = {};
+    this._aliases = {};
 
     // @ts-ignore
     this._root$Ref = null;
@@ -205,6 +222,11 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    * @returns {object}
    */
   toJSON = this.values;
+
+  private _getRef(path: string) {
+    const withoutHash = url.stripHash(path);
+    return this._$refs[withoutHash] || this._aliases[withoutHash];
+  }
 }
 
 /**

package/lib/resolve-external.ts

@@ -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";
 import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types/index.js";
@@ -29,7 +30,14 @@ function resolveExternal<S extends object = JSONSchema, O extends ParserOptions<
 
   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) {
     return Promise.reject(e);
@@ -55,6 +63,8 @@ function resolveExternal<S extends object = JSONSchema, O extends ParserOptions<
 function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   obj: string | Buffer | S | undefined | null,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   $refs: $Refs<S, O>,
   options: O,
   seen?: Set<any>,
@@ -65,15 +75,18 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
 
   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<S, O>(obj, path, $refs, options));
+      promises.push(resolve$Ref<S, O>(obj, path, currentScopeBase, dynamicIdScope, $refs, options));
     }
 
     const keys = Object.keys(obj) as string[];
     for (const key of keys) {
       const keyPath = Pointer.join(path, key);
       const value = obj[key as keyof typeof obj] as string | JSONSchema | Buffer | undefined;
-      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));
     }
   }
 
@@ -95,17 +108,20 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
 async function resolve$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   $ref: S,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   $refs: $Refs<S, O>,
   options: O,
 ) {
   const shouldResolveOnCwd = options.dereference?.externalReferenceResolution === "root";
-  const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, ($ref as JSONSchema).$ref!);
+  const resolutionBase = shouldResolveOnCwd ? url.cwd() : dynamicIdScope ? scopeBase : path;
+  const resolvedPath = url.resolve(resolutionBase, ($ref as JSONSchema).$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);
@@ -113,11 +129,33 @@ async function resolve$Ref<S extends object = JSONSchema, O extends ParserOption
 
   // Parse the $referenced file/url
   try {
-    const result = await parse(resolvedPath, $refs, options);
+    const reference = ($ref as JSONSchema).$ref;
+    const parseTarget: { url: string; baseUrl: string; reference?: string } = {
+      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/lib/types/index.ts

@@ -139,6 +139,19 @@ export interface FileInfo {
    */
   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.
    */