fix: resolve cross-type case-name collisions in registered component ids

document.AddComponent is TryAdd (first writer wins, never throws), and
component ids were bare case/definition names — so two different F#
types sharing a case name (e.g. both having a "Leaf" or "Error" case)
would silently collide in the same OpenAPI document, with the second
type's schema never actually registering under its own definition.

Qualify every definition id with its owning root type's name
(rootTypeId + "." + typeId) when bound to a live document; the
document-agnostic translate() entry point is unaffected (qualify is
identity when document = None), so all pre-existing structural tests
keep passing unchanged. The "." separator is required, not cosmetic:
without it, different (rootTypeId, typeId) pairs can concatenate to
the same string (e.g. "Order"+"LineItem" = "OrderLine"+"Item").

Also addresses the remaining deferred Minor findings from final
review: precondition guard on rootTypeId, doc-comment scope fixes,
restored net9 comment, and a WebApplication dispose leak in the e2e
test fixtures.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: panesofglass

RELEASE_NOTES.md

@@ -3,6 +3,7 @@
 * Fix `InvalidOperationException: The input schema must be an OpenApiSchema or OpenApiSchemaReference` thrown by `Microsoft.AspNetCore.OpenApi` 10.0.3+ for any endpoint whose request/response type is (or contains) an F# discriminated union or a self-recursive type (#30)
 * `FSharpSchemaTransformer` now registers component schemas into the live `OpenApiDocument` on net10 instead of leaving them unregistered with dangling references
 * Fix self-recursive types (e.g. a tree or linked-list shaped DU) all resolving their self-reference to the same hardcoded component id on net10; each now gets its own correctly-named component
+* On net10, definition/component ids (DU cases and nested referenced types alike) are now qualified by their owning root type's name (e.g. `TreeNode.Leaf` instead of `Leaf`), so two different types that happen to share a case or type name no longer silently collide in `components/schemas`
 
 ### FSharp.Data.JsonSchema.NJsonSchema 3.1.0
 

src/FSharp.Data.JsonSchema.OpenApi/FSharpSchemaTransformer.fs

@@ -91,6 +91,9 @@ type FSharpSchemaTransformer(config: SchemaGeneratorConfig) =
                     | null -> OpenApiSchemaTranslator.translate doc
                     | document -> OpenApiSchemaTranslator.translateForDocument doc rootTypeId document
 #else
+                // net9 (Microsoft.OpenApi.Models) has no live-document concept to register
+                // components into — component schemas are never registered here, unchanged
+                // from before this fix; only the net10 path (above) registers them.
                 let (translatedRoot, _componentSchemas) = OpenApiSchemaTranslator.translate doc
 #endif
 

src/FSharp.Data.JsonSchema.OpenApi/OpenApiSchemaTranslator.fs

@@ -120,6 +120,21 @@ module OpenApiSchemaTranslator =
         let componentSchemas = Collections.Generic.Dictionary<string, OpenApiSchema>()
         let rootSchema = mkSchema ()
 
+        // Case/definition-level ids are qualified with `rootTypeId` only when bound to a live
+        // document, so two different types that happen to share a case name (e.g. both having
+        // an "Error" case) register distinct components instead of the second silently
+        // overwriting the first. The document-agnostic `translate` entry point (document = None)
+        // keeps ids unqualified, since it never registers into a shared namespace.
+        // The "." separator (valid in OpenAPI component ids) is required, not cosmetic: without
+        // it, two different (rootTypeId, typeId) pairs can concatenate to the same string (e.g.
+        // "Order" + "LineItem" = "OrderLine" + "Item" = "OrderLineItem") — same collision class
+        // this qualification exists to close, just narrower. Neither a .NET Type.Name nor an
+        // F# union case name can contain ".", so the split stays unambiguous.
+        let qualify (typeId: string) : string =
+            match document with
+            | Some _ -> rootTypeId + "." + typeId
+            | None -> typeId
+
         let rec translateNode (node: SchemaNode) : OpenApiSchema =
             match node with
             | SchemaNode.Object obj ->
@@ -178,7 +193,7 @@ module OpenApiSchemaTranslator =
                 schema
 
             | SchemaNode.Ref typeId ->
-                let resolvedId = if typeId = "#" then rootTypeId else typeId
+                let resolvedId = if typeId = "#" then rootTypeId else qualify typeId
 #if NET10_0_OR_GREATER
                 mkRefSchema document resolvedId
 #else
@@ -205,9 +220,10 @@ module OpenApiSchemaTranslator =
         // document (when supplied) as it's produced.
         for (key, value) in doc.Definitions do
             let componentSchema = translateNode value
-            componentSchemas.[key] <- componentSchema
+            let registeredKey = qualify key
+            componentSchemas.[registeredKey] <- componentSchema
 #if NET10_0_OR_GREATER
-            document |> Option.iter (fun d -> d.AddComponent(key, componentSchema) |> ignore)
+            document |> Option.iter (fun d -> d.AddComponent(registeredKey, componentSchema) |> ignore)
 #endif
 
         // Translate root
@@ -250,17 +266,23 @@ module OpenApiSchemaTranslator =
         (result, componentSchemas |> Seq.map (fun kv -> kv.Key, kv.Value) |> Map.ofSeq)
 
     /// Translate a SchemaDocument to an OpenApiSchema and component schemas.
-    /// Self-refs and component references are unbound (no host document) — suitable for
-    /// structural inspection but not for live OpenAPI document generation, where
-    /// `translateForDocument` must be used instead so references actually resolve.
+    /// On net10, self-refs and component references are left unbound (no host document) —
+    /// suitable for structural inspection but not for live OpenAPI document generation,
+    /// where `translateForDocument` must be used instead so references actually resolve.
+    /// On net9, references are always produced via `OpenApiReference` metadata directly;
+    /// this distinction doesn't apply there.
     let translate (doc: SchemaDocument) : OpenApiSchema * Map<string, OpenApiSchema> =
         translateCore doc "root" None
 
 #if NET10_0_OR_GREATER
     /// Translate a SchemaDocument, binding component and self-ref references to a live
     /// OpenApiDocument so they resolve correctly, and registering component schemas
     /// — including the root schema itself, under `rootTypeId`, whenever there are any
-    /// definitions — into `document.Components.Schemas`.
+    /// definitions — into `document.Components.Schemas`. The returned component map
+    /// mirrors `translate`'s signature; registration already happened as a side effect
+    /// against `document`, so callers that only need the live document can discard it.
     let translateForDocument (doc: SchemaDocument) (rootTypeId: string) (document: OpenApiDocument) : OpenApiSchema * Map<string, OpenApiSchema> =
+        if String.IsNullOrEmpty rootTypeId then
+            invalidArg (nameof rootTypeId) "rootTypeId must not be null or empty"
         translateCore doc rootTypeId (Some document)
 #endif

test/FSharp.Data.JsonSchema.OpenApi.Tests/EndToEndTests.fs

@@ -29,6 +29,13 @@ type LinkedNode =
     | Empty
     | Node of value: int * next: LinkedNode
 
+/// Shares a case name ("Leaf") with TreeNode, to prove case-name collisions
+/// across different types are resolved by qualifying component ids with the
+/// owning type's name.
+type Plant =
+    | Leaf of species: string
+    | Root of Plant
+
 let private startApp (mapEndpoints: WebApplication -> unit) : WebApplication =
     let builder = WebApplication.CreateBuilder()
     builder.Logging.ClearProviders() |> ignore
@@ -40,10 +47,18 @@ let private startApp (mapEndpoints: WebApplication -> unit) : WebApplication =
         options.AddSchemaTransformer(FSharpSchemaTransformer()) |> ignore
     ) |> ignore
     let app = builder.Build()
-    app.MapOpenApi() |> ignore
-    mapEndpoints app
-    app.StartAsync().GetAwaiter().GetResult()
-    app
+    try
+        app.MapOpenApi() |> ignore
+        mapEndpoints app
+        app.StartAsync().GetAwaiter().GetResult()
+        app
+    with _ ->
+        app.DisposeAsync().AsTask().GetAwaiter().GetResult()
+        reraise ()
+
+let private stopApp (app: WebApplication) : unit =
+    app.StopAsync().GetAwaiter().GetResult()
+    app.DisposeAsync().AsTask().GetAwaiter().GetResult()
 
 let private baseAddress (app: WebApplication) : string =
     let server = app.Services.GetRequiredService<IServer>()
@@ -75,36 +90,36 @@ let endToEndTests =
                 use jsonDoc = JsonDocument.Parse body
 #if NET10_0_OR_GREATER
                 let root = jsonDoc.RootElement
-                Expect.isTrue (hasSchema root "Circle") "Circle registered as a component schema"
-                Expect.isTrue (hasSchema root "Rectangle") "Rectangle registered as a component schema"
-                Expect.isTrue (hasSchema root "Point") "Point registered as a component schema"
+                Expect.isTrue (hasSchema root "Shape.Circle") "Circle registered as a component schema, qualified by its type"
+                Expect.isTrue (hasSchema root "Shape.Rectangle") "Rectangle registered as a component schema, qualified by its type"
+                Expect.isTrue (hasSchema root "Shape.Point") "Point registered as a component schema, qualified by its type"
 #endif
                 ()
             finally
-                app.StopAsync().GetAwaiter().GetResult()
+                stopApp app
         }
 
         test "OpenAPI document generation succeeds for a self-recursive discriminated union" {
-            let app = startApp (fun app -> app.MapGet("/tree", System.Func<TreeNode>(fun () -> Leaf 1)) |> ignore)
+            let app = startApp (fun app -> app.MapGet("/tree", System.Func<TreeNode>(fun () -> TreeNode.Leaf 1)) |> ignore)
             try
                 let (status, body) = getOpenApiDocument app
                 Expect.equal status System.Net.HttpStatusCode.OK "200 OK, not the InvalidOperationException from #30"
                 use jsonDoc = JsonDocument.Parse body
 #if NET10_0_OR_GREATER
                 let root = jsonDoc.RootElement
-                Expect.isTrue (hasSchema root "Leaf") "Leaf registered as a component schema"
-                Expect.isTrue (hasSchema root "Branch") "Branch registered as a component schema"
+                Expect.isTrue (hasSchema root "TreeNode.Leaf") "Leaf registered as a component schema, qualified by its type"
+                Expect.isTrue (hasSchema root "TreeNode.Branch") "Branch registered as a component schema, qualified by its type"
                 Expect.isTrue (hasSchema root "TreeNode") "TreeNode root registered as a component schema (self-ref target)"
 #endif
                 ()
             finally
-                app.StopAsync().GetAwaiter().GetResult()
+                stopApp app
         }
 
         test "OpenAPI document generation registers distinct components for two different self-recursive types" {
             let app =
                 startApp (fun app ->
-                    app.MapGet("/tree", System.Func<TreeNode>(fun () -> Leaf 1)) |> ignore
+                    app.MapGet("/tree", System.Func<TreeNode>(fun () -> TreeNode.Leaf 1)) |> ignore
                     app.MapGet("/linked", System.Func<LinkedNode>(fun () -> Empty)) |> ignore
                 )
             try
@@ -114,14 +129,36 @@ let endToEndTests =
 #if NET10_0_OR_GREATER
                 let root = jsonDoc.RootElement
                 Expect.isTrue (hasSchema root "TreeNode") "TreeNode root registered as a component schema"
-                Expect.isTrue (hasSchema root "Leaf") "Leaf registered as a component schema"
-                Expect.isTrue (hasSchema root "Branch") "Branch registered as a component schema"
+                Expect.isTrue (hasSchema root "TreeNode.Leaf") "Leaf registered as a component schema, qualified by its type"
+                Expect.isTrue (hasSchema root "TreeNode.Branch") "Branch registered as a component schema, qualified by its type"
                 Expect.isTrue (hasSchema root "LinkedNode") "LinkedNode root registered as a component schema"
-                Expect.isTrue (hasSchema root "Empty") "Empty registered as a component schema"
-                Expect.isTrue (hasSchema root "Node") "Node registered as a component schema"
+                Expect.isTrue (hasSchema root "LinkedNode.Empty") "Empty registered as a component schema, qualified by its type"
+                Expect.isTrue (hasSchema root "LinkedNode.Node") "Node registered as a component schema, qualified by its type"
+#endif
+                ()
+            finally
+                stopApp app
+        }
+
+        test "OpenAPI document generation disambiguates two different types sharing a case name" {
+            let app =
+                startApp (fun app ->
+                    app.MapGet("/tree", System.Func<TreeNode>(fun () -> TreeNode.Leaf 1)) |> ignore
+                    app.MapGet("/plant", System.Func<Plant>(fun () -> Plant.Leaf "fern")) |> ignore
+                )
+            try
+                let (status, body) = getOpenApiDocument app
+                Expect.equal status System.Net.HttpStatusCode.OK "200 OK, not the InvalidOperationException from #30"
+                use jsonDoc = JsonDocument.Parse body
+#if NET10_0_OR_GREATER
+                let root = jsonDoc.RootElement
+                // TreeNode and Plant both have a case named "Leaf" — proving neither
+                // silently overwrites the other's component is the point of this test.
+                Expect.isTrue (hasSchema root "TreeNode.Leaf") "TreeNode's Leaf case registered under its own qualified id"
+                Expect.isTrue (hasSchema root "Plant.Leaf") "Plant's Leaf case registered under its own qualified id"
 #endif
                 ()
             finally
-                app.StopAsync().GetAwaiter().GetResult()
+                stopApp app
         }
     ]

test/FSharp.Data.JsonSchema.OpenApi.Tests/TranslatorTests.fs

@@ -240,18 +240,42 @@ let documentBindingTests =
             let (schema: OASchema, _components) =
                 OpenApiSchemaTranslator.translateForDocument doc "Root" document
             Expect.isNotNull (document.Components :> obj) "components created"
-            Expect.isTrue (document.Components.Schemas.ContainsKey "A") "A registered"
-            Expect.isTrue (document.Components.Schemas.ContainsKey "B") "B registered"
+            // Definition ids are qualified with rootTypeId ("Root") when bound to a live
+            // document, so "A"/"B" register as "Root.A"/"Root.B" — see the case-collision
+            // test below for why.
+            Expect.isTrue (document.Components.Schemas.ContainsKey "Root.A") "A registered under its qualified id"
+            Expect.isTrue (document.Components.Schemas.ContainsKey "Root.B") "B registered under its qualified id"
             // Ref nodes are translated by mkRefSchema into a schema whose sole AnyOf
             // element is the OpenApiSchemaReference; translateNode's return type is
             // OpenApiSchema (not IOpenApiSchema), so the reference can't be returned
             // unwrapped directly into the outer AnyOf collection — mirrors the unwrap
             // pattern used below for the self-ref case.
             let refWrapperA = schema.AnyOf.[0] :?> OASchema
             let refA = refWrapperA.AnyOf.[0] :?> OpenApiSchemaReference
+            Expect.equal refA.Reference.Id "Root.A" "ref points at the qualified id"
             Expect.isNotNull (refA.Target :> obj) "ref A resolves to a non-null target"
         }
 
+        test "translateForDocument qualifies case ids so two types sharing a case name don't collide" {
+            let docTreeNode = {
+                Root = SchemaNode.Ref "Leaf"
+                Definitions = [ "Leaf", SchemaNode.Primitive(PrimitiveType.String, None) ]
+            }
+            let docPlant = {
+                Root = SchemaNode.Ref "Leaf"
+                Definitions = [ "Leaf", SchemaNode.Primitive(PrimitiveType.Integer, Some "int32") ]
+            }
+            let document = OpenApiDocument()
+            OpenApiSchemaTranslator.translateForDocument docTreeNode "TreeNode" document |> ignore
+            OpenApiSchemaTranslator.translateForDocument docPlant "Plant" document |> ignore
+            Expect.isTrue (document.Components.Schemas.ContainsKey "TreeNode.Leaf") "TreeNode's Leaf case registered under a qualified id"
+            Expect.isTrue (document.Components.Schemas.ContainsKey "Plant.Leaf") "Plant's Leaf case registered under a qualified id"
+            let treeLeaf = document.Components.Schemas.["TreeNode.Leaf"] :?> OASchema
+            let plantLeaf = document.Components.Schemas.["Plant.Leaf"] :?> OASchema
+            Expect.equal treeLeaf.Type (System.Nullable(JsonSchemaType.String)) "TreeNode's Leaf kept its own (string) type, not overwritten by Plant's"
+            Expect.equal plantLeaf.Type (System.Nullable(JsonSchemaType.Integer)) "Plant's Leaf kept its own (integer) type, not overwritten by TreeNode's"
+        }
+
         test "translateForDocument binds self-ref to the given rootTypeId and registers the root component" {
             let doc = {
                 Root = SchemaNode.Object {