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

package/dist/lib/bundle.js

@@ -14,10 +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)
-    fixRefsThroughRefs(inventory, parser.schema);
+    const bundleOptions = (options.bundle || {});
+    if (bundleOptions.optimizeInternalRefs !== false) {
+        fixRefsThroughRefs(inventory, parser.schema);
+    }
 }
 /**
  * Recursively crawls the given value, and inventories all JSON references.
@@ -157,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) {
@@ -202,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
@@ -339,4 +364,25 @@ function walkPath(schema, path) {
     }
     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

@@ -83,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) {

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 {
     /**
@@ -78,6 +86,20 @@ export interface DereferenceOptions {
      * Default: 500
      */
     maxDepth?: number;
+    /**
+     * Whether to create independent clones of each `$ref` target value instead of
+     * reusing the same JS object reference. When `false` (the default), multiple
+     * `$ref` pointers that resolve to the same value will all share the same object
+     * in memory, so modifying one will affect all others. When `true`, each `$ref`
+     * replacement gets its own deep copy, preventing unintended side effects from
+     * post-dereference mutations.
+     *
+     * Note: circular references are never cloned — they always maintain reference
+     * equality to correctly represent the circular structure.
+     *
+     * Default: `false`
+     */
+    cloneReferences?: boolean;
 }
 /**
  * Options that determine how JSON schemas are parsed, resolved, and dereferenced.

package/lib/bundle.ts

@@ -39,11 +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)
-  fixRefsThroughRefs(inventory, parser.schema as any);
+  const bundleOptions = (options.bundle || {}) as BundleOptions;
+  if (bundleOptions.optimizeInternalRefs !== false) {
+    fixRefsThroughRefs(inventory, parser.schema as any);
+  }
 }
 
 /**
@@ -209,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) => {
@@ -256,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;
@@ -409,4 +435,26 @@ function walkPath(schema: any, path: string): any {
   return current;
 }
 
+/**
+ * Checks whether the given inventory entry is located inside a sub-schema that has its own $id.
+ * If so, root-relative JSON Pointer $refs placed at this location would be resolved against
+ * the $id base URI rather than the document root, making them invalid.
+ */
+function isInsideIdScope(inventory: InventoryEntry[], entry: InventoryEntry): boolean {
+  for (const other of inventory) {
+    // Skip root-level entries
+    if (other.pathFromRoot === "#" || other.pathFromRoot === "#/") {
+      continue;
+    }
+    // Check if the other entry is an ancestor of the current entry
+    if (entry.pathFromRoot.startsWith(other.pathFromRoot + "/")) {
+      // Check if the ancestor's resolved value has a $id
+      if (other.value && typeof other.value === "object" && "$id" in other.value) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 export default bundle;

package/lib/dereference.ts

@@ -146,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.

package/lib/options.ts

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

package/package.json

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