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

package/dist/lib/bundle.js

@@ -14,8 +14,17 @@ function bundle(parser, options) {
     // 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);
+    // 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
+        : undefined;
     // Remap all $ref pointers
-    remap(inventory, options);
+    remap(inventory, options, rootId);
+    // Fix any $ref paths that traverse through other $refs (which is invalid per JSON Schema spec)
+    const bundleOptions = (options.bundle || {});
+    if (bundleOptions.optimizeInternalRefs !== false) {
+        fixRefsThroughRefs(inventory, parser.schema);
+    }
 }
 /**
  * Recursively crawls the given value, and inventories all JSON references.
@@ -155,7 +164,7 @@ function inventory$Ref($refParent, $refKey, path, pathFromRoot, indirections, in
  *
  * @param inventory
  */
-function remap(inventory, options) {
+function remap(inventory, options, rootId) {
     // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
     inventory.sort((a, b) => {
         if (a.file !== b.file) {
@@ -200,17 +209,35 @@ function remap(inventory, options) {
     let file, hash, pathFromRoot;
     for (const entry of inventory) {
         // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
+        const bundleOpts = (options.bundle || {});
         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
@@ -261,4 +288,101 @@ function removeFromInventory(inventory, entry) {
     const index = inventory.indexOf(entry);
     inventory.splice(index, 1);
 }
+/**
+ * After remapping, some $ref paths may traverse through other $ref nodes.
+ * JSON pointer resolution does not follow $ref indirection, so these paths are invalid.
+ * This function detects and fixes such paths by following any intermediate $refs
+ * to compute a valid direct path.
+ */
+function fixRefsThroughRefs(inventory, schema) {
+    for (const entry of inventory) {
+        if (!entry.$ref || typeof entry.$ref !== "object" || !("$ref" in entry.$ref)) {
+            continue;
+        }
+        const refValue = entry.$ref.$ref;
+        if (typeof refValue !== "string" || !refValue.startsWith("#/")) {
+            continue;
+        }
+        const fixedPath = resolvePathThroughRefs(schema, refValue);
+        if (fixedPath !== refValue) {
+            entry.$ref.$ref = fixedPath;
+        }
+    }
+}
+/**
+ * Walks a JSON pointer path through the schema. If any intermediate value
+ * is a $ref, follows it and adjusts the path accordingly.
+ * Returns the corrected path that doesn't traverse through any $ref.
+ */
+function resolvePathThroughRefs(schema, refPath) {
+    if (!refPath.startsWith("#/")) {
+        return refPath;
+    }
+    const segments = refPath.slice(2).split("/");
+    let current = schema;
+    const resolvedSegments = [];
+    for (const seg of segments) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            // Can't walk further, return original path
+            return refPath;
+        }
+        // If the current value is a $ref, follow it
+        if ("$ref" in current && typeof current.$ref === "string" && current.$ref.startsWith("#/")) {
+            // Follow the $ref and restart the path from its target
+            const targetSegments = current.$ref.slice(2).split("/");
+            resolvedSegments.length = 0;
+            resolvedSegments.push(...targetSegments);
+            current = walkPath(schema, current.$ref);
+            if (current === null || current === undefined || typeof current !== "object") {
+                return refPath;
+            }
+        }
+        const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+        const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+        current = current[idx];
+        resolvedSegments.push(seg);
+    }
+    const result = "#/" + resolvedSegments.join("/");
+    return result;
+}
+/**
+ * Walks a JSON pointer path through a schema object, returning the value at that path.
+ */
+function walkPath(schema, path) {
+    if (!path.startsWith("#/")) {
+        return undefined;
+    }
+    const segments = path.slice(2).split("/");
+    let current = schema;
+    for (const seg of segments) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+        const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+        current = current[idx];
+    }
+    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, entry) {
+    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/dist/lib/dereference.js

@@ -13,7 +13,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);
+    const dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, "#", new Set(), new Set(), new Map(), parser.$refs, options, start, 0);
     parser.$refs.circular = dereferenced.circular;
     parser.schema = dereferenced.value;
 }
@@ -29,9 +29,10 @@ function dereference(parser, options) {
  * @param $refs
  * @param options
  * @param startTime - The time when the dereferencing started
+ * @param depth - The current recursion depth
  * @returns
  */
-function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime) {
+function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
     let dereferenced;
     const result = {
         value: obj,
@@ -39,13 +40,19 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
     };
     checkDereferenceTimeout(startTime, options);
     const derefOptions = (options.dereference || {});
+    const maxDepth = derefOptions.maxDepth ?? 500;
+    if (depth > maxDepth) {
+        throw new RangeError(`Maximum dereference depth (${maxDepth}) exceeded at ${pathFromRoot}. ` +
+            `This likely indicates an extremely deep or recursive schema. ` +
+            `You can increase this limit with the dereference.maxDepth option.`);
+    }
     const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
     if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
         if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
             parents.add(obj);
             processedObjects.add(obj);
             if ($Ref.isAllowed$Ref(obj, options)) {
-                dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime);
+                dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
                 result.circular = dereferenced.circular;
                 result.value = dereferenced.value;
             }
@@ -58,9 +65,9 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
                         continue;
                     }
                     const value = obj[key];
-                    let circular = false;
+                    let circular;
                     if ($Ref.isAllowed$Ref(value, options)) {
-                        dereferenced = dereference$Ref(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime);
+                        dereferenced = dereference$Ref(value, keyPath, 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) {
@@ -76,7 +83,13 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
                                     });
                                 }
                             }
-                            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.
                             if (derefOptions?.preservedProperties) {
@@ -91,7 +104,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);
+                            dereferenced = crawl(value, keyPath, 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) {
@@ -124,7 +137,7 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
  * @param options
  * @returns
  */
-function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime) {
+function dereference$Ref($ref, path, 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);
@@ -197,7 +210,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);
+        const dereferenced = crawl(dereferencedValue, pointer.path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
         circular = dereferenced.circular;
         dereferencedValue = dereferenced.value;
     }

package/dist/lib/options.d.ts

@@ -18,6 +18,14 @@ 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 {
     /**
@@ -70,6 +78,28 @@ export interface DereferenceOptions {
      * Default: `true`
      */
     mergeKeys?: boolean;
+    /**
+     * The maximum recursion depth for dereferencing nested schemas.
+     * If the schema nesting exceeds this depth, a RangeError will be thrown
+     * with a descriptive message instead of crashing with a stack overflow.
+     *
+     * 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;
 }
 /**
  * Options that determine how JSON schemas are parsed, resolved, and dereferenced.

package/dist/lib/parse.js

@@ -67,7 +67,7 @@ async function readFile(file, options, $refs) {
         }
         else if (!err || !("error" in err)) {
             // Throw a generic, friendly error.
-            throw new SyntaxError(`Unable to resolve $ref pointer "${file.url}"`);
+            throw new SyntaxError(`Unable to resolve $ref pointer "${file.url}"`, { cause: err });
         }
         // Throw the original error, if it's one of our own (user-friendly) errors.
         else if (err.error instanceof ResolverError) {
@@ -118,7 +118,7 @@ async function parseFile(file, options, $refs) {
             throw err;
         }
         else if (!err || !("error" in err)) {
-            throw new SyntaxError(`Unable to parse ${file.url}`);
+            throw new SyntaxError(`Unable to parse ${file.url}`, { cause: err });
         }
         else if (err.error instanceof ParserError) {
             throw err.error;

package/dist/lib/pointer.js

@@ -69,10 +69,24 @@ class Pointer {
         // Crawl the object, one token at a time
         this.value = unwrapOrThrow(obj);
         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
+            // as circular because the $ref resolves to the same path we're walking, we should
+            // reset the circular flag and continue walking the object's own properties.
+            // This prevents false circular detection when e.g. a root schema has both
+            // $ref: "#/$defs/Foo" and $defs: { Foo: {...} } as siblings.
+            const wasCircular = this.circular;
+            const isExtendedRef = $Ref.isExtended$Ref(this.value);
             if (resolveIf$Ref(this, options, pathFromRoot)) {
                 // The $ref path has changed, so append the remaining tokens to the path
                 this.path = Pointer.join(this.path, tokens.slice(i));
             }
+            else if (!wasCircular && this.circular && isExtendedRef) {
+                // resolveIf$Ref set circular=true on an extended $ref during token walking.
+                // Since we still have tokens to process, the object should be walked by its
+                // properties, not treated as a circular self-reference.
+                this.circular = false;
+            }
             const token = tokens[i];
             if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
                 // one final case is if the entry itself includes slashes, and was parsed out as a token - we can join the remaining tokens and try again

package/lib/bundle.ts

@@ -39,8 +39,20 @@ function bundle<S extends object = JSONSchema, O extends ParserOptions<S> = Pars
   const inventory: InventoryEntry[] = [];
   crawl<S, O>(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 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)
+  const bundleOptions = (options.bundle || {}) as BundleOptions;
+  if (bundleOptions.optimizeInternalRefs !== false) {
+    fixRefsThroughRefs(inventory, parser.schema as any);
+  }
 }
 
 /**
@@ -206,6 +218,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) => {
@@ -253,15 +266,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;
@@ -316,4 +345,116 @@ function removeFromInventory(inventory: InventoryEntry[], entry: any) {
   const index = inventory.indexOf(entry);
   inventory.splice(index, 1);
 }
+
+/**
+ * After remapping, some $ref paths may traverse through other $ref nodes.
+ * JSON pointer resolution does not follow $ref indirection, so these paths are invalid.
+ * This function detects and fixes such paths by following any intermediate $refs
+ * to compute a valid direct path.
+ */
+function fixRefsThroughRefs(inventory: InventoryEntry[], schema: any) {
+  for (const entry of inventory) {
+    if (!entry.$ref || typeof entry.$ref !== "object" || !("$ref" in entry.$ref)) {
+      continue;
+    }
+
+    const refValue = entry.$ref.$ref;
+    if (typeof refValue !== "string" || !refValue.startsWith("#/")) {
+      continue;
+    }
+
+    const fixedPath = resolvePathThroughRefs(schema, refValue);
+    if (fixedPath !== refValue) {
+      entry.$ref.$ref = fixedPath;
+    }
+  }
+}
+
+/**
+ * Walks a JSON pointer path through the schema. If any intermediate value
+ * is a $ref, follows it and adjusts the path accordingly.
+ * Returns the corrected path that doesn't traverse through any $ref.
+ */
+function resolvePathThroughRefs(schema: any, refPath: string): string {
+  if (!refPath.startsWith("#/")) {
+    return refPath;
+  }
+
+  const segments = refPath.slice(2).split("/");
+  let current = schema;
+  const resolvedSegments: string[] = [];
+
+  for (const seg of segments) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      // Can't walk further, return original path
+      return refPath;
+    }
+
+    // If the current value is a $ref, follow it
+    if ("$ref" in current && typeof current.$ref === "string" && current.$ref.startsWith("#/")) {
+      // Follow the $ref and restart the path from its target
+      const targetSegments = current.$ref.slice(2).split("/");
+      resolvedSegments.length = 0;
+      resolvedSegments.push(...targetSegments);
+      current = walkPath(schema, current.$ref);
+      if (current === null || current === undefined || typeof current !== "object") {
+        return refPath;
+      }
+    }
+
+    const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+    current = current[idx];
+    resolvedSegments.push(seg);
+  }
+
+  const result = "#/" + resolvedSegments.join("/");
+  return result;
+}
+
+/**
+ * Walks a JSON pointer path through a schema object, returning the value at that path.
+ */
+function walkPath(schema: any, path: string): any {
+  if (!path.startsWith("#/")) {
+    return undefined;
+  }
+
+  const segments = path.slice(2).split("/");
+  let current = schema;
+
+  for (const seg of segments) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      return undefined;
+    }
+    const decoded = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    const idx = Array.isArray(current) ? parseInt(decoded) : decoded;
+    current = current[idx];
+  }
+
+  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

@@ -31,6 +31,7 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
     parser.$refs,
     options,
     start,
+    0,
   );
   parser.$refs.circular = dereferenced.circular;
   parser.schema = dereferenced.value;
@@ -48,6 +49,7 @@ function dereference<S extends object = JSONSchema, O extends ParserOptions<S> =
  * @param $refs
  * @param options
  * @param startTime - The time when the dereferencing started
+ * @param depth - The current recursion depth
  * @returns
  */
 function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
@@ -60,6 +62,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   $refs: $Refs<S, O>,
   options: O,
   startTime: number,
+  depth: number,
 ) {
   let dereferenced;
   const result = {
@@ -70,6 +73,14 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   checkDereferenceTimeout<S, O>(startTime, options);
 
   const derefOptions = (options.dereference || {}) as DereferenceOptions;
+  const maxDepth = derefOptions.maxDepth ?? 500;
+  if (depth > maxDepth) {
+    throw new RangeError(
+      `Maximum dereference depth (${maxDepth}) exceeded at ${pathFromRoot}. ` +
+        `This likely indicates an extremely deep or recursive schema. ` +
+        `You can increase this limit with the dereference.maxDepth option.`,
+    );
+  }
   const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
 
   if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
@@ -88,6 +99,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
           $refs,
           options,
           startTime,
+          depth,
         );
         result.circular = dereferenced.circular;
         result.value = dereferenced.value;
@@ -103,7 +115,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
           }
 
           const value = obj[key];
-          let circular = false;
+          let circular;
 
           if ($Ref.isAllowed$Ref(value, options)) {
             dereferenced = dereference$Ref(
@@ -116,6 +128,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
               $refs,
               options,
               startTime,
+              depth,
             );
             circular = dereferenced.circular;
             // Avoid pointless mutations; breaks frozen objects to no profit
@@ -133,7 +146,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.
@@ -159,6 +179,7 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
                 $refs,
                 options,
                 startTime,
+                depth + 1,
               );
               circular = dereferenced.circular;
               // Avoid pointless mutations; breaks frozen objects to no profit
@@ -205,6 +226,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
   $refs: $Refs<S, O>,
   options: O,
   startTime: number,
+  depth: number,
 ) {
   const isExternalRef = $Ref.isExternal$Ref($ref);
   const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
@@ -295,6 +317,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
       $refs,
       options,
       startTime,
+      depth + 1,
     );
     circular = dereferenced.circular;
     dereferencedValue = dereferenced.value;

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 {
@@ -89,6 +98,30 @@ export interface DereferenceOptions {
    * Default: `true`
    */
   mergeKeys?: boolean;
+
+  /**
+   * The maximum recursion depth for dereferencing nested schemas.
+   * If the schema nesting exceeds this depth, a RangeError will be thrown
+   * with a descriptive message instead of crashing with a stack overflow.
+   *
+   * 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

@@ -91,7 +91,7 @@ async function readFile<S extends object = JSONSchema, O extends ParserOptions<S
       throw new UnmatchedResolverError(file.url);
     } else if (!err || !("error" in err)) {
       // Throw a generic, friendly error.
-      throw new SyntaxError(`Unable to resolve $ref pointer "${file.url}"`);
+      throw new SyntaxError(`Unable to resolve $ref pointer "${file.url}"`, { cause: err });
     }
     // Throw the original error, if it's one of our own (user-friendly) errors.
     else if (err.error instanceof ResolverError) {
@@ -143,7 +143,7 @@ async function parseFile<S extends object = JSONSchema, O extends ParserOptions<
     } else if (err && err.message && err.message.startsWith("Error parsing")) {
       throw err;
     } else if (!err || !("error" in err)) {
-      throw new SyntaxError(`Unable to parse ${file.url}`);
+      throw new SyntaxError(`Unable to parse ${file.url}`, { cause: err });
     } else if (err.error instanceof ParserError) {
       throw err.error;
     } else {

package/lib/pointer.ts

@@ -89,9 +89,22 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
     this.value = unwrapOrThrow(obj);
 
     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
+      // as circular because the $ref resolves to the same path we're walking, we should
+      // reset the circular flag and continue walking the object's own properties.
+      // This prevents false circular detection when e.g. a root schema has both
+      // $ref: "#/$defs/Foo" and $defs: { Foo: {...} } as siblings.
+      const wasCircular = this.circular;
+      const isExtendedRef = $Ref.isExtended$Ref(this.value);
       if (resolveIf$Ref(this, options, pathFromRoot)) {
         // The $ref path has changed, so append the remaining tokens to the path
         this.path = Pointer.join(this.path, tokens.slice(i));
+      } else if (!wasCircular && this.circular && isExtendedRef) {
+        // resolveIf$Ref set circular=true on an extended $ref during token walking.
+        // Since we still have tokens to process, the object should be walked by its
+        // properties, not treated as a circular self-reference.
+        this.circular = false;
       }
 
       const token = tokens[i];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "15.2.2",
+  "version": "15.3.1",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "type": "module",
   "types": "dist/lib/index.d.ts",
@@ -75,28 +75,28 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.1",
-    "@eslint/js": "^9.39.2",
+    "@eslint/compat": "^2.0.2",
+    "@eslint/js": "^10.0.1",
     "@types/eslint": "^9.6.1",
     "@types/js-yaml": "^4.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "^4.0.18",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-promise": "^7.2.1",
-    "eslint-plugin-unused-imports": "^4.3.0",
-    "globals": "^17.1.0",
-    "jsdom": "^27.4.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "globals": "^17.3.0",
+    "jsdom": "^28.1.0",
     "prettier": "^3.8.1",
-    "rimraf": "^6.1.2",
+    "rimraf": "^6.1.3",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
   },
   "release": {