json-schema: key bundled $defs entries by explicit @id to prevent silent overwrite

.chronus/changes/copilot-bug-fix-duplicate-id-resolution-2026-6-31-12-29-40.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/json-schema"
+---
+
+Use explicit `@id` values for bundled $defs keys to avoid silent overwrites.

packages/json-schema/src/json-schema-emitter.ts

@@ -84,6 +84,7 @@ import { includeDerivedModel } from "./utils.js";
 export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSchemaEmitterOptions> {
   #idDuplicateTracker = new DuplicateTracker<string, DiagnosticTarget>();
   #typeForSourceFile = new Map<SourceFile<any>, JsonSchemaDeclaration>();
+  #declDefKey = new Map<Declaration<any>, string>();
 
   #applyModelIndexer(schema: ObjectBuilder<unknown>, model: Model) {
     if (model.indexer) {
@@ -733,6 +734,10 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
     const decl = this.emitter.result.declaration(name, schema);
     const sf = (decl.scope as SourceFileScope<any>).sourceFile;
     sf.meta.shouldEmit = this.#shouldEmitRootSchema(type);
+    const explicitId = getId(this.emitter.getProgram(), type);
+    if (explicitId) {
+      this.#declDefKey.set(decl, explicitId);
+    }
     return decl;
   }
 
@@ -964,7 +969,8 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
       };
       for (const sf of sourceFiles) {
         if (sf.meta.shouldEmit) {
-          content.$defs[sf.globalScope.declarations[0].name] = this.#finalizeSourceFileContent(sf);
+          const decl = sf.globalScope.declarations[0];
+          content.$defs[this.#getDefKey(decl)] = this.#finalizeSourceFileContent(sf);
         }
       }
       await emitFile(this.emitter.getProgram(), {
@@ -1016,7 +1022,7 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
           continue;
         }
         bundledDecls.add(decl);
-        content.$defs[decl.name] = decl.value;
+        content.$defs[this.#getDefKey(decl)] = decl.value;
 
         // all scopes are source file scopes in this emitter
         const refSf = (decl.scope as SourceFileScope<any>).sourceFile;
@@ -1082,6 +1088,10 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
     return id;
   }
 
+  #getDefKey(decl: Declaration<any>): string {
+    return this.#declDefKey.get(decl) ?? decl.name;
+  }
+
   // #region context emitters
   modelDeclarationContext(model: Model, name: string): Context {
     if (this.#isStdType(model) && (model.name as any) === "object") {

packages/json-schema/test/ids.test.ts

@@ -90,6 +90,29 @@ describe("explicit ids with $id", () => {
       { bundleId: "types.json" },
     );
 
-    assert.strictEqual(schemas["types.json"].$defs.Foo.$id, "http://example.org/bar");
+    assert.strictEqual(schemas["types.json"].$defs.bar.$id, "http://example.org/bar");
+  });
+
+  it("uses explicit id values as $defs keys in bundle mode", async () => {
+    const schemas = await emitSchema(
+      `
+      @jsonSchema
+      namespace StringExpressions {
+        @id("StringEquals")
+        model Equals { equals: string; }
+      }
+
+      @jsonSchema
+      namespace IntegerExpressions {
+        @id("IntegerEquals")
+        model Equals { equals: integer; }
+      }
+      `,
+      { bundleId: "types.json" },
+      { emitNamespace: false },
+    );
+
+    assert.strictEqual(schemas["types.json"].$defs.StringEquals.properties.equals.type, "string");
+    assert.strictEqual(schemas["types.json"].$defs.IntegerEquals.properties.equals.type, "integer");
   });
 });