fix: resolve multiple open issues (#349, #355, #392) and add regression tests (#415)

- Add `dereference.cloneReferences` option to create independent copies
  of dereferenced values via structuredClone, preventing shared-reference
  mutations (#349)
- Fix bundle creating invalid cross-$id $ref pointers by qualifying refs
  with the root document's $id when inside a sub-schema $id scope (#355)
- Add `bundle.optimizeInternalRefs` option to control whether internal
  $ref paths get shortened during bundling (#392)
- Add regression tests for #384 (externalReferenceResolution) and #403
  (circular $ref: "#" in oneOf)

Author: jonluca

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;

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.

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;
 }
 
 /**

test/specs/bundle-id-refs/base.schema.json

@@ -0,0 +1,8 @@
+{
+  "$id": "base.schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "foo": { "type": "string" }
+  }
+}

test/specs/bundle-id-refs/bundle-id-refs.spec.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import $RefParser from "../../../lib/index.js";
+import path from "../../utils/path.js";
+
+describe("Bundle with $id in sub-schemas (issue #355)", () => {
+  it("should not create invalid cross-$id $ref pointers when bundling", async () => {
+    const parser = new $RefParser();
+    const bundled = await parser.bundle(path.rel("test/specs/bundle-id-refs/root.schema.json"));
+
+    // The bundled schema should have both sub-schemas inlined
+    expect(bundled.oneOf).toHaveLength(2);
+
+    const sub1 = bundled.oneOf[0];
+    const sub2 = bundled.oneOf[1];
+
+    // sub1 should have the base schema inlined in its allOf
+    expect(sub1.$id).toBe("sub1.schema.json");
+    expect(sub1.allOf[0]).toHaveProperty("$id", "base.schema.json");
+    expect(sub1.allOf[0]).toHaveProperty("type", "object");
+
+    // sub2 also references base.schema.json. Since sub2 has $id: "sub2.schema.json",
+    // a bare #/oneOf/0/allOf/0 ref would resolve relative to sub2's $id, which is wrong.
+    // The bundler should qualify the ref with the root $id.
+    expect(sub2.$id).toBe("sub2.schema.json");
+
+    const sub2BaseRef = sub2.allOf[0];
+    // The ref should be qualified with the root $id to avoid $id scoping issues
+    expect(sub2BaseRef.$ref).toBe("root.schema.json#/oneOf/0/allOf/0");
+  });
+});

test/specs/bundle-id-refs/root.schema.json

@@ -0,0 +1,6 @@
+{
+  "$id": "root.schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "oneOf": [{ "$ref": "sub1.schema.json" }, { "$ref": "sub2.schema.json" }]
+}

test/specs/bundle-id-refs/sub1.schema.json

@@ -0,0 +1,6 @@
+{
+  "$id": "sub1.schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "allOf": [{ "$ref": "base.schema.json" }, { "properties": { "name": { "type": "string", "const": "sub1" } } }]
+}

test/specs/bundle-id-refs/sub2.schema.json

@@ -0,0 +1,6 @@
+{
+  "$id": "sub2.schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "allOf": [{ "$ref": "base.schema.json" }, { "properties": { "name": { "type": "string", "const": "sub2" } } }]
+}

test/specs/bundle-no-optimize/bundle-no-optimize.spec.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import $RefParser from "../../../lib/index.js";
+import path from "../../utils/path.js";
+
+describe("bundle.optimizeInternalRefs option (issue #392)", () => {
+  it("should optimize internal ref chains by default", async () => {
+    const parser = new $RefParser();
+    const bundled = await parser.bundle(path.rel("test/specs/bundle-no-optimize/root.json"));
+
+    // By default, fixRefsThroughRefs optimizes the chain:
+    // item -> #/definitions/extended -> #/definitions/base
+    // becomes: item -> #/definitions/base (skipping intermediate)
+    expect(bundled.properties.item.$ref).toBe("#/definitions/base");
+  });
+
+  it("should preserve internal ref chains when optimizeInternalRefs is false", async () => {
+    const parser = new $RefParser();
+    const bundled = await parser.bundle(path.rel("test/specs/bundle-no-optimize/root.json"), {
+      bundle: { optimizeInternalRefs: false },
+    });
+
+    // With optimization disabled, the original chain is preserved:
+    // item still points to #/definitions/extended
+    expect(bundled.properties.item.$ref).toBe("#/definitions/extended");
+  });
+});

test/specs/bundle-no-optimize/root.json

@@ -0,0 +1,19 @@
+{
+  "type": "object",
+  "definitions": {
+    "base": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" }
+      }
+    },
+    "extended": {
+      "$ref": "#/definitions/base"
+    }
+  },
+  "properties": {
+    "item": {
+      "$ref": "#/definitions/extended"
+    }
+  }
+}