@apidevtools/json-schema-ref-parser 15.3.6 → 15.5.0

package/dist/lib/bundle.d.ts

@@ -13,6 +13,7 @@ export interface InventoryEntry {
     circular: any;
     extended: any;
     external: any;
+    nestedResource: boolean;
     indirections: any;
 }
 /**

package/dist/lib/bundle.js

@@ -119,6 +119,7 @@ function inventory$Ref($refParent, $refKey, path, scopeBase, dynamicIdScope, pat
     const file = url.stripHash(pointer.path);
     const hash = url.getHash(pointer.path);
     const external = file !== $refs._root$Ref.path && !$refs._aliases[file];
+    const nestedResource = Boolean($refs._aliases[file]) && pointer.$ref.value !== $refs._root$Ref.value;
     const extended = $Ref.isExtended$Ref($ref);
     indirections += pointer.indirections;
     const existingEntry = findInInventory(inventory, $refParent, $refKey);
@@ -143,6 +144,7 @@ function inventory$Ref($refParent, $refKey, path, scopeBase, dynamicIdScope, pat
         circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
         extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
         external, // Does this $ref pointer point to a file other than the main JSON Schema file?
+        nestedResource, // Does this $ref resolve to an embedded schema resource with its own $id?
         indirections, // The number of indirect references that were traversed to resolve the value
     });
     // Recursively crawl the resolved value
@@ -221,8 +223,10 @@ function remap(inventory, options, rootId) {
         if (!entry.external) {
             // 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) {
+            // instead of rewriting it to the fully resolved hash. References to nested
+            // resources must also retain their resource URI so that "#" does not point
+            // at the document root instead.
+            if (bundleOpts.optimizeInternalRefs !== false && !entry.nestedResource) {
                 entry.$ref.$ref = entry.hash;
             }
         }

package/dist/lib/dereference.js

@@ -210,7 +210,7 @@ function dereference$Ref($ref, path, scopeBase, dynamicIdScope, pathFromRoot, pa
     }
     // Check for circular references
     const directCircular = pointer.circular;
-    let circular = directCircular || parents.has(pointer.value);
+    let circular = directCircular || pointer.chainCircular || parents.has(pointer.value);
     if (circular) {
         foundCircularReference(path, $refs, options);
     }
@@ -227,7 +227,7 @@ function dereference$Ref($ref, path, scopeBase, dynamicIdScope, pathFromRoot, pa
         // The user has chosen to "ignore" circular references, so don't change the value
         dereferencedValue = $ref;
     }
-    if (directCircular) {
+    if (directCircular && dereferencedValue !== $ref) {
         // The pointer is a DIRECT circular reference (i.e. it references itself).
         // So replace the $ref path with the absolute path from the JSON Schema root
         dereferencedValue.$ref = pathFromRoot;

package/dist/lib/options.d.ts

@@ -82,6 +82,7 @@ export interface DereferenceOptions {
      * 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.
+     * This limit also applies to `$ref` resolution chains.
      *
      * Default: 500
      */

package/dist/lib/pointer.d.ts

@@ -38,6 +38,10 @@ declare class Pointer<S extends object = JSONSchema, O extends ParserOptions<S>
      * Indicates whether the pointer references itself.
      */
     circular: boolean;
+    /**
+     * Indicates whether the pointer encountered a cycle elsewhere in its reference chain.
+     */
+    chainCircular: boolean;
     /**
      * The number of indirect references that were traversed to resolve the value.
      * Resolving a single pointer may require resolving multiple $Refs.
@@ -57,7 +61,7 @@ declare class Pointer<S extends object = JSONSchema, O extends ParserOptions<S>
      * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
      * of the resolved value.
      */
-    resolve(obj: S, options?: O, pathFromRoot?: string): this;
+    resolve(obj: S, options?: O, pathFromRoot?: string, visitedRefPaths?: Set<string>, resolveFinalReference?: boolean): this;
     /**
      * Sets the value of a nested property within the given object.
      *

package/dist/lib/pointer.js

@@ -43,6 +43,10 @@ class Pointer {
      * Indicates whether the pointer references itself.
      */
     circular;
+    /**
+     * Indicates whether the pointer encountered a cycle elsewhere in its reference chain.
+     */
+    chainCircular;
     /**
      * The number of indirect references that were traversed to resolve the value.
      * Resolving a single pointer may require resolving multiple $Refs.
@@ -55,6 +59,7 @@ class Pointer {
         this.scopeBase = $ref.path || url.stripHash(path);
         this.value = undefined;
         this.circular = false;
+        this.chainCircular = false;
         this.indirections = 0;
     }
     /**
@@ -70,7 +75,7 @@ class Pointer {
      * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
      * of the resolved value.
      */
-    resolve(obj, options, pathFromRoot) {
+    resolve(obj, options, pathFromRoot, visitedRefPaths = new Set(), resolveFinalReference = true) {
         const tokens = Pointer.parse(this.path, this.originalPath);
         const found = [];
         // Crawl the object, one token at a time
@@ -86,16 +91,18 @@ class Pointer {
             // 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 wasChainCircular = this.chainCircular;
             const isExtendedRef = $Ref.isExtended$Ref(this.value);
-            if (resolveIf$Ref(this, options, pathFromRoot)) {
+            if (resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths)) {
                 // 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) {
+            else if (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;
+                this.circular = wasCircular;
+                this.chainCircular = wasChainCircular;
             }
             const token = tokens[i];
             if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
@@ -111,6 +118,7 @@ class Pointer {
                     }
                 }
                 if (didFindSubstringSlashMatch) {
+                    this.chainCircular = wasChainCircular;
                     continue;
                 }
                 // If the token we're looking for ended up not containing any slashes but is
@@ -120,6 +128,7 @@ class Pointer {
                     // We use a `null` symbol for internal tracking to differentiate between a general `null`
                     // value and our expected `null` value.
                     this.value = nullSymbol;
+                    this.chainCircular = wasChainCircular;
                     continue;
                 }
                 this.value = null;
@@ -132,6 +141,7 @@ class Pointer {
             else {
                 this.value = this.value[token];
             }
+            this.chainCircular = wasChainCircular;
             found.push(token);
             if (this.$ref.dynamicIdScope) {
                 this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
@@ -139,8 +149,17 @@ class Pointer {
         }
         // Resolve the final value
         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);
+        if (resolveFinalReference) {
+            const finalRefPath = this.value?.$ref ? url.resolve(finalResolutionBase, this.value.$ref) : undefined;
+            const canonicalPathFromRoot = typeof pathFromRoot === "string" ? url.resolve(this.$ref.$refs._root$Ref.path, pathFromRoot) : pathFromRoot;
+            if ($Ref.isAllowed$Ref(this.value, options) &&
+                finalRefPath === canonicalPathFromRoot &&
+                finalRefPath !== this.path) {
+                this.chainCircular = true;
+            }
+            else if (!this.value || finalRefPath) {
+                resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths);
+            }
         }
         return this;
     }
@@ -256,26 +275,58 @@ class Pointer {
  * @param [pathFromRoot] - the path of place that initiated resolving
  * @returns - Returns `true` if the resolution path changed
  */
-function resolveIf$Ref(pointer, options, pathFromRoot) {
-    // Is the value a JSON reference? (and allowed?)
-    if ($Ref.isAllowed$Ref(pointer.value, options)) {
-        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;
-        }
-        else {
-            const resolved = pointer.$ref.$refs._resolve($refPath, pointer.path, options);
+function resolveIf$Ref(pointer, options, pathFromRoot, visitedRefPaths = new Set()) {
+    let pathChanged = false;
+    let currentPathFromRoot = pathFromRoot;
+    const addedPaths = [];
+    try {
+        // Pure reference chains can be followed iteratively. Extended refs still use
+        // the existing one-hop behavior because their values must be merged on return.
+        while ($Ref.isAllowed$Ref(pointer.value, options)) {
+            const extended = $Ref.isExtended$Ref(pointer.value);
+            const sourceValue = pointer.value;
+            const parentPath = pointer.path;
+            const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
+            const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
+            if ($refPath === pointer.path && !isRootPath(currentPathFromRoot)) {
+                // The value is a reference to itself, so there's nothing to do.
+                pointer.circular = true;
+                pointer.chainCircular = true;
+                return pathChanged;
+            }
+            const canonicalPathFromRoot = typeof currentPathFromRoot === "string"
+                ? url.resolve(pointer.$ref.$refs._root$Ref.path, currentPathFromRoot)
+                : currentPathFromRoot;
+            if ($refPath === canonicalPathFromRoot && $refPath !== pointer.path) {
+                pointer.chainCircular = true;
+                return pathChanged;
+            }
+            if (visitedRefPaths.has($refPath)) {
+                pointer.chainCircular = true;
+                return pathChanged;
+            }
+            const maxDepth = options?.dereference?.maxDepth ?? 500;
+            if (visitedRefPaths.size >= maxDepth) {
+                throw new RangeError(`Maximum dereference depth (${maxDepth}) exceeded at ${pointer.path}. ` +
+                    `This likely indicates an extremely deep or recursive schema. ` +
+                    `You can increase this limit with the dereference.maxDepth option.`);
+            }
+            visitedRefPaths.add($refPath);
+            addedPaths.push($refPath);
+            const resolved = pointer.$ref.$refs._resolve($refPath, parentPath, options, visitedRefPaths, extended);
             if (resolved === null) {
-                return false;
+                return pathChanged;
             }
             pointer.indirections += resolved.indirections + 1;
-            if ($Ref.isExtended$Ref(pointer.value)) {
+            pointer.chainCircular ||= resolved.circular || resolved.chainCircular;
+            if (extended) {
                 // 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);
-                return false;
+                if (pointer.chainCircular) {
+                    return pathChanged;
+                }
+                pointer.value = $Ref.dereference(sourceValue, resolved.value, options);
+                return pathChanged;
             }
             else {
                 // Resolve the reference
@@ -285,12 +336,18 @@ function resolveIf$Ref(pointer, options, pathFromRoot) {
                 // `pointer.$ref.path` is already the canonical location of the resolved resource.
                 // Re-applying the resource's own `$id` here would duplicate nested path segments
                 // such as `nested/nested/foo.json`.
-                pointer.scopeBase = pointer.$ref.path;
+                pointer.scopeBase = resolved.scopeBase;
+                currentPathFromRoot = parentPath;
+                pathChanged = true;
             }
-            return true;
+        }
+        return pathChanged;
+    }
+    finally {
+        for (const path of addedPaths) {
+            visitedRefPaths.delete(path);
         }
     }
-    return undefined;
 }
 export default Pointer;
 /**

package/dist/lib/ref.d.ts

@@ -78,9 +78,11 @@ declare class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = P
      * @param options
      * @param friendlyPath - The original user-specified path (used for error messages)
      * @param pathFromRoot - The path of `obj` from the schema root
+     * @param visitedRefPaths - the active paths in the current reference chain
+     * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
      * @returns
      */
-    resolve(path: string, options?: O, friendlyPath?: string, pathFromRoot?: string): Pointer<S, O> | null;
+    resolve(path: string, options?: O, friendlyPath?: string, pathFromRoot?: string, visitedRefPaths?: Set<string>, resolveFinalReference?: boolean): Pointer<S, O> | null;
     /**
      * Sets the value of a nested property within this {@link $Ref#value}.
      * If the property, or any of its parents don't exist, they will be created.

package/dist/lib/ref.js

@@ -100,12 +100,14 @@ class $Ref {
      * @param options
      * @param friendlyPath - The original user-specified path (used for error messages)
      * @param pathFromRoot - The path of `obj` from the schema root
+     * @param visitedRefPaths - the active paths in the current reference chain
+     * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
      * @returns
      */
-    resolve(path, options, friendlyPath, pathFromRoot) {
+    resolve(path, options, friendlyPath, pathFromRoot, visitedRefPaths, resolveFinalReference = true) {
         const pointer = new Pointer(this, path, friendlyPath);
         try {
-            const resolved = pointer.resolve(this.value, options, pathFromRoot);
+            const resolved = pointer.resolve(this.value, options, pathFromRoot, visitedRefPaths, resolveFinalReference);
             if (resolved.value === nullSymbol) {
                 resolved.value = null;
             }

package/dist/lib/refs.d.ts

@@ -86,10 +86,12 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
      * @param path - The path being resolved, optionally with a JSON pointer in the hash
      * @param pathFromRoot - The path of `obj` from the schema root
      * @param [options]
+     * @param visitedRefPaths - the active paths in the current reference chain
+     * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
      * @returns
      * @protected
      */
-    _resolve(path: string, pathFromRoot: string, options?: O): import("./pointer.js").default<S, O> | null;
+    _resolve(path: string, pathFromRoot: string, options?: O, visitedRefPaths?: Set<string>, resolveFinalReference?: boolean): import("./pointer.js").default<S, O> | null;
     /**
      * A map of paths/urls to {@link $Ref} objects
      *

package/dist/lib/refs.js

@@ -133,16 +133,18 @@ export default class $Refs {
      * @param path - The path being resolved, optionally with a JSON pointer in the hash
      * @param pathFromRoot - The path of `obj` from the schema root
      * @param [options]
+     * @param visitedRefPaths - the active paths in the current reference chain
+     * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
      * @returns
      * @protected
      */
-    _resolve(path, pathFromRoot, options) {
+    _resolve(path, pathFromRoot, options, visitedRefPaths, resolveFinalReference = true) {
         const absPath = url.resolve(this._root$Ref.path, path);
         const $ref = this._getRef(absPath);
         if (!$ref) {
             throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
         }
-        return $ref.resolve(absPath, options, path, pathFromRoot);
+        return $ref.resolve(absPath, options, path, pathFromRoot, visitedRefPaths, resolveFinalReference);
     }
     /**
      * A map of paths/urls to {@link $Ref} objects

package/lib/bundle.ts

@@ -20,6 +20,7 @@ export interface InventoryEntry {
   circular: any;
   extended: any;
   external: any;
+  nestedResource: boolean;
   indirections: any;
 }
 /**
@@ -194,6 +195,7 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   const file = url.stripHash(pointer.path);
   const hash = url.getHash(pointer.path);
   const external = file !== $refs._root$Ref.path && !$refs._aliases[file];
+  const nestedResource = Boolean($refs._aliases[file]) && pointer.$ref.value !== $refs._root$Ref.value;
   const extended = $Ref.isExtended$Ref($ref);
   indirections += pointer.indirections;
 
@@ -219,6 +221,7 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
     circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
     extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
     external, // Does this $ref pointer point to a file other than the main JSON Schema file?
+    nestedResource, // Does this $ref resolve to an embedded schema resource with its own $id?
     indirections, // The number of indirect references that were traversed to resolve the value
   });
 
@@ -316,8 +319,10 @@ function remap<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
     if (!entry.external) {
       // 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) {
+      // instead of rewriting it to the fully resolved hash. References to nested
+      // resources must also retain their resource URI so that "#" does not point
+      // at the document root instead.
+      if (bundleOpts.optimizeInternalRefs !== false && !entry.nestedResource) {
         entry.$ref.$ref = entry.hash;
       }
     } else if (entry.file === file && entry.hash === hash) {

package/lib/dereference.ts

@@ -318,7 +318,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
 
   // Check for circular references
   const directCircular = pointer.circular;
-  let circular = directCircular || parents.has(pointer.value);
+  let circular = directCircular || pointer.chainCircular || parents.has(pointer.value);
   if (circular) {
     foundCircularReference(path, $refs, options);
   }
@@ -352,7 +352,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
     dereferencedValue = $ref;
   }
 
-  if (directCircular) {
+  if (directCircular && dereferencedValue !== $ref) {
     // The pointer is a DIRECT circular reference (i.e. it references itself).
     // So replace the $ref path with the absolute path from the JSON Schema root
     dereferencedValue.$ref = pathFromRoot;

package/lib/options.ts

@@ -103,6 +103,7 @@ export interface DereferenceOptions {
    * 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.
+   * This limit also applies to `$ref` resolution chains.
    *
    * Default: 500
    */

package/lib/pointer.ts

@@ -55,6 +55,10 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    * Indicates whether the pointer references itself.
    */
   circular: boolean;
+  /**
+   * Indicates whether the pointer encountered a cycle elsewhere in its reference chain.
+   */
+  chainCircular: boolean;
   /**
    * The number of indirect references that were traversed to resolve the value.
    * Resolving a single pointer may require resolving multiple $Refs.
@@ -74,6 +78,8 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     this.circular = false;
 
+    this.chainCircular = false;
+
     this.indirections = 0;
   }
 
@@ -90,7 +96,13 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
    * of the resolved value.
    */
-  resolve(obj: S, options?: O, pathFromRoot?: string) {
+  resolve(
+    obj: S,
+    options?: O,
+    pathFromRoot?: string,
+    visitedRefPaths = new Set<string>(),
+    resolveFinalReference = true,
+  ) {
     const tokens = Pointer.parse(this.path, this.originalPath);
     const found: string[] = [];
 
@@ -108,15 +120,17 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
       // 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 wasChainCircular = this.chainCircular;
       const isExtendedRef = $Ref.isExtended$Ref(this.value);
-      if (resolveIf$Ref(this, options, pathFromRoot)) {
+      if (resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths)) {
         // 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) {
+      } else if (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;
+        this.circular = wasCircular;
+        this.chainCircular = wasChainCircular;
       }
 
       const token = tokens[i];
@@ -134,6 +148,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
           }
         }
         if (didFindSubstringSlashMatch) {
+          this.chainCircular = wasChainCircular;
           continue;
         }
 
@@ -144,6 +159,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
           // We use a `null` symbol for internal tracking to differentiate between a general `null`
           // value and our expected `null` value.
           this.value = nullSymbol;
+          this.chainCircular = wasChainCircular;
           continue;
         }
 
@@ -160,6 +176,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         this.value = this.value[token];
       }
 
+      this.chainCircular = wasChainCircular;
       found.push(token);
       if (this.$ref.dynamicIdScope) {
         this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
@@ -168,8 +185,20 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // Resolve the final value
     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);
+    if (resolveFinalReference) {
+      const finalRefPath = this.value?.$ref ? url.resolve(finalResolutionBase, this.value.$ref) : undefined;
+      const canonicalPathFromRoot =
+        typeof pathFromRoot === "string" ? url.resolve(this.$ref.$refs._root$Ref.path!, pathFromRoot) : pathFromRoot;
+
+      if (
+        $Ref.isAllowed$Ref(this.value, options) &&
+        finalRefPath === canonicalPathFromRoot &&
+        finalRefPath !== this.path
+      ) {
+        this.chainCircular = true;
+      } else if (!this.value || finalRefPath) {
+        resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths);
+      }
     }
 
     return this;
@@ -305,32 +334,74 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
  * @returns - Returns `true` if the resolution path changed
  */
 function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-  pointer: Pointer,
+  pointer: Pointer<S, O>,
   options: O | undefined,
   pathFromRoot?: string,
+  visitedRefPaths = new Set<string>(),
 ) {
-  // Is the value a JSON reference? (and allowed?)
+  let pathChanged = false;
+  let currentPathFromRoot = pathFromRoot;
+  const addedPaths: string[] = [];
+
+  try {
+    // Pure reference chains can be followed iteratively. Extended refs still use
+    // the existing one-hop behavior because their values must be merged on return.
+    while ($Ref.isAllowed$Ref(pointer.value, options)) {
+      const extended = $Ref.isExtended$Ref(pointer.value);
+      const sourceValue = pointer.value;
+      const parentPath = pointer.path;
+      const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
+      const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
+
+      if ($refPath === pointer.path && !isRootPath(currentPathFromRoot)) {
+        // The value is a reference to itself, so there's nothing to do.
+        pointer.circular = true;
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
 
-  if ($Ref.isAllowed$Ref(pointer.value, options)) {
-    const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
-    const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
+      const canonicalPathFromRoot =
+        typeof currentPathFromRoot === "string"
+          ? url.resolve(pointer.$ref.$refs._root$Ref.path!, currentPathFromRoot)
+          : currentPathFromRoot;
+      if ($refPath === canonicalPathFromRoot && $refPath !== pointer.path) {
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
 
-    if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
-      // The value is a reference to itself, so there's nothing to do.
-      pointer.circular = true;
-    } else {
-      const resolved = pointer.$ref.$refs._resolve($refPath, pointer.path, options);
+      if (visitedRefPaths.has($refPath)) {
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
+
+      const maxDepth = options?.dereference?.maxDepth ?? 500;
+      if (visitedRefPaths.size >= maxDepth) {
+        throw new RangeError(
+          `Maximum dereference depth (${maxDepth}) exceeded at ${pointer.path}. ` +
+            `This likely indicates an extremely deep or recursive schema. ` +
+            `You can increase this limit with the dereference.maxDepth option.`,
+        );
+      }
+
+      visitedRefPaths.add($refPath);
+      addedPaths.push($refPath);
+
+      const resolved = pointer.$ref.$refs._resolve($refPath, parentPath, options, visitedRefPaths, extended);
       if (resolved === null) {
-        return false;
+        return pathChanged;
       }
 
       pointer.indirections += resolved.indirections + 1;
+      pointer.chainCircular ||= resolved.circular || resolved.chainCircular;
 
-      if ($Ref.isExtended$Ref(pointer.value)) {
+      if (extended) {
         // 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);
-        return false;
+        if (pointer.chainCircular) {
+          return pathChanged;
+        }
+        pointer.value = $Ref.dereference(sourceValue, resolved.value, options);
+        return pathChanged;
       } else {
         // Resolve the reference
         pointer.$ref = resolved.$ref;
@@ -339,13 +410,18 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
         // `pointer.$ref.path` is already the canonical location of the resolved resource.
         // Re-applying the resource's own `$id` here would duplicate nested path segments
         // such as `nested/nested/foo.json`.
-        pointer.scopeBase = pointer.$ref.path!;
+        pointer.scopeBase = resolved.scopeBase;
+        currentPathFromRoot = parentPath;
+        pathChanged = true;
       }
+    }
 
-      return true;
+    return pathChanged;
+  } finally {
+    for (const path of addedPaths) {
+      visitedRefPaths.delete(path);
     }
   }
-  return undefined;
 }
 export default Pointer;
 

package/lib/ref.ts

@@ -120,12 +120,21 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    * @param options
    * @param friendlyPath - The original user-specified path (used for error messages)
    * @param pathFromRoot - The path of `obj` from the schema root
+   * @param visitedRefPaths - the active paths in the current reference chain
+   * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
    * @returns
    */
-  resolve(path: string, options?: O, friendlyPath?: string, pathFromRoot?: string) {
+  resolve(
+    path: string,
+    options?: O,
+    friendlyPath?: string,
+    pathFromRoot?: string,
+    visitedRefPaths?: Set<string>,
+    resolveFinalReference = true,
+  ) {
     const pointer = new Pointer<S, O>(this, path, friendlyPath);
     try {
-      const resolved = pointer.resolve(this.value, options, pathFromRoot);
+      const resolved = pointer.resolve(this.value, options, pathFromRoot, visitedRefPaths, resolveFinalReference);
       if (resolved.value === nullSymbol) {
         resolved.value = null;
       }

package/lib/refs.ts

@@ -155,10 +155,18 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    * @param path - The path being resolved, optionally with a JSON pointer in the hash
    * @param pathFromRoot - The path of `obj` from the schema root
    * @param [options]
+   * @param visitedRefPaths - the active paths in the current reference chain
+   * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
    * @returns
    * @protected
    */
-  _resolve(path: string, pathFromRoot: string, options?: O) {
+  _resolve(
+    path: string,
+    pathFromRoot: string,
+    options?: O,
+    visitedRefPaths?: Set<string>,
+    resolveFinalReference = true,
+  ) {
     const absPath = url.resolve(this._root$Ref.path!, path);
     const $ref = this._getRef(absPath);
 
@@ -166,7 +174,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
       throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
     }
 
-    return $ref.resolve(absPath, options, path, pathFromRoot);
+    return $ref.resolve(absPath, options, path, pathFromRoot, visitedRefPaths, resolveFinalReference);
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "15.3.6",
+  "version": "15.5.0",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "type": "module",
   "types": "dist/lib/index.d.ts",