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

package/dist/lib/bundle.js

@@ -16,6 +16,8 @@ function bundle(parser, options) {
     crawl(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
     // Remap all $ref pointers
     remap(inventory, options);
+    // Fix any $ref paths that traverse through other $refs (which is invalid per JSON Schema spec)
+    fixRefsThroughRefs(inventory, parser.schema);
 }
 /**
  * Recursively crawls the given value, and inventories all JSON references.
@@ -261,4 +263,80 @@ 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;
+}
 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) {
@@ -91,7 +98,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 +131,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 +204,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

@@ -70,6 +70,14 @@ 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;
 }
 /**
  * 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

@@ -41,6 +41,9 @@ function bundle<S extends object = JSONSchema, O extends ParserOptions<S> = Pars
 
   // Remap all $ref pointers
   remap<S, O>(inventory, options);
+
+  // Fix any $ref paths that traverse through other $refs (which is invalid per JSON Schema spec)
+  fixRefsThroughRefs(inventory, parser.schema as any);
 }
 
 /**
@@ -316,4 +319,94 @@ 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;
+}
+
 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
@@ -159,6 +172,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 +219,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 +310,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

@@ -89,6 +89,15 @@ 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;
 }
 
 /**

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.0",
   "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": {