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

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;
+}

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,13 +38,33 @@ 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 =
+    parser.schema && typeof parser.schema === "object" && "$id" in (parser.schema as any)
+      ? (parser.schema as any).$id
+      : undefined;
 
   // Remap all $ref pointers
-  remap<S, O>(inventory, options);
+  remap<S, O>(inventory, options, rootId);
 
   // Fix any $ref paths that traverse through other $refs (which is invalid per JSON Schema spec)
-  fixRefsThroughRefs(inventory, parser.schema as any);
+  const bundleOptions = (options.bundle || {}) as BundleOptions;
+  if (bundleOptions.optimizeInternalRefs !== false) {
+    fixRefsThroughRefs(inventory, parser.schema as any);
+  }
 }
 
 /**
@@ -62,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[],
@@ -73,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,
@@ -99,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
@@ -133,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[],
@@ -140,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;
@@ -149,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;
 
@@ -180,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,
+    );
   }
 }
 
@@ -209,6 +258,7 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
 function remap<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   inventory: InventoryEntry[],
   options: O,
+  rootId?: string,
 ) {
   // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
   inventory.sort((a: InventoryEntry, b: InventoryEntry) => {
@@ -256,15 +306,31 @@ function remap<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   for (const entry of inventory) {
     // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
 
+    const bundleOpts = (options.bundle || {}) as BundleOptions;
     if (!entry.external) {
-      // This $ref already resolves to the main JSON Schema file
-      entry.$ref.$ref = entry.hash;
+      // This $ref already resolves to the main JSON Schema file.
+      // When optimizeInternalRefs is false, preserve the original internal ref path
+      // instead of rewriting it to the fully resolved hash.
+      if (bundleOpts.optimizeInternalRefs !== false) {
+        entry.$ref.$ref = entry.hash;
+      }
     } else if (entry.file === file && entry.hash === hash) {
       // This $ref points to the same value as the previous $ref, so remap it to the same path
-      entry.$ref.$ref = pathFromRoot;
+      if (rootId && isInsideIdScope(inventory, entry)) {
+        // This entry is inside a sub-schema with its own $id, so a bare root-relative JSON Pointer
+        // would be resolved relative to that $id, not the document root. Qualify with the root $id.
+        entry.$ref.$ref = rootId + pathFromRoot;
+      } else {
+        entry.$ref.$ref = pathFromRoot;
+      }
     } else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
       // This $ref points to a sub-value of the previous $ref, so remap it beneath that path
-      entry.$ref.$ref = Pointer.join(pathFromRoot, Pointer.parse(entry.hash.replace(hash, "#")));
+      const subPath = Pointer.join(pathFromRoot, Pointer.parse(entry.hash.replace(hash, "#")));
+      if (rootId && isInsideIdScope(inventory, entry)) {
+        entry.$ref.$ref = rootId + subPath;
+      } else {
+        entry.$ref.$ref = subPath;
+      }
     } else {
       // We've moved to a new file or new hash
       file = entry.file;
@@ -409,4 +475,26 @@ function walkPath(schema: any, path: string): any {
   return current;
 }
 
+/**
+ * Checks whether the given inventory entry is located inside a sub-schema that has its own $id.
+ * If so, root-relative JSON Pointer $refs placed at this location would be resolved against
+ * the $id base URI rather than the document root, making them invalid.
+ */
+function isInsideIdScope(inventory: InventoryEntry[], entry: InventoryEntry): boolean {
+  for (const other of inventory) {
+    // Skip root-level entries
+    if (other.pathFromRoot === "#" || other.pathFromRoot === "#/") {
+      continue;
+    }
+    // Check if the other entry is an ancestor of the current entry
+    if (entry.pathFromRoot.startsWith(other.pathFromRoot + "/")) {
+      // Check if the ancestor's resolved value has a $id
+      if (other.value && typeof other.value === "object" && "$id" in other.value) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 export default bundle;

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,
@@ -146,7 +157,14 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
                 }
               }
 
-              obj[key] = dereferenced.value;
+              // Clone the dereferenced value if cloneReferences is enabled and this is not a
+              // circular reference. This prevents mutations to one location from affecting others.
+              let assignedValue = dereferenced.value;
+              if (derefOptions?.cloneReferences && !circular && assignedValue && typeof assignedValue === "object") {
+                assignedValue = structuredClone(assignedValue);
+              }
+
+              obj[key] = assignedValue;
 
               // If we have data to preserve and our dereferenced object is still an object then
               // we need copy back our preserved data into our dereferenced schema.
@@ -165,6 +183,8 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
               dereferenced = crawl(
                 value,
                 keyPath,
+                currentScopeBase,
+                dynamicIdScope,
                 keyPathFromRoot,
                 parents,
                 processedObjects,
@@ -212,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,
@@ -223,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);
 
@@ -303,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/options.ts

@@ -30,6 +30,15 @@ export interface BundleOptions {
    * @argument {string} parentPropName - The prop name of the parent object whose value was processed
    */
   onBundle?(path: string, value: JSONSchemaObject, parent?: JSONSchemaObject, parentPropName?: string): void;
+
+  /**
+   * Whether to optimize internal `$ref` paths by following intermediate `$ref` chains and
+   * rewriting them to point directly to the final target. When `false`, intermediate `$ref`
+   * indirections are preserved as-is.
+   *
+   * Default: `true`
+   */
+  optimizeInternalRefs?: boolean;
 }
 
 export interface DereferenceOptions {
@@ -98,6 +107,21 @@ export interface DereferenceOptions {
    * Default: 500
    */
   maxDepth?: number;
+
+  /**
+   * Whether to create independent clones of each `$ref` target value instead of
+   * reusing the same JS object reference. When `false` (the default), multiple
+   * `$ref` pointers that resolve to the same value will all share the same object
+   * in memory, so modifying one will affect all others. When `true`, each `$ref`
+   * replacement gets its own deep copy, preventing unintended side effects from
+   * post-dereference mutations.
+   *
+   * Note: circular references are never cloned — they always maintain reference
+   * equality to correctly represent the circular structure.
+   *
+   * Default: `false`
+   */
+  cloneReferences?: boolean;
 }
 
 /**

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) {