fix: inline format-annotated primitives instead of dangling component refs (#29) (#34)

DateTime, DateTimeOffset, DateOnly, TimeOnly, Guid, Uri, and TimeSpan fields
were routed through SchemaAnalyzer's Ref/definitions path, producing a
needless $ref to a single-purpose component (e.g. "WeatherForecast.DateTime")
instead of an inline {"type": "string", "format": "date-time"} schema.

Scoped the fix to the OpenApi package via a new
OpenApiSchemaTranslator.inlineFormatOnlyDefinitions pass, run before
translation, rather than changing Core's SchemaAnalyzer — that would have
altered the main NJsonSchema package's byte-identical snapshot output for
the same types, which is intentional, tested behavior there.


Claude-Session: https://claude.ai/code/session_01Bs5FwyUrCG4dpj3JygXu3J

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: panesofglass

RELEASE_NOTES.md

@@ -5,6 +5,7 @@
 * 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`
 * Pin the net10 `Microsoft.OpenApi` dependency to 2.9.0 (was transitively 2.0.0), above the version affected by GHSA-v5pm-xwqc-g5wc
+* Fix format-annotated types (`DateTime`, `DateTimeOffset`, `DateOnly`, `TimeOnly`, `Guid`, `Uri`, `TimeSpan`) generating a needless `$ref` to a single-purpose component (e.g. `WeatherForecast.DateTime`) instead of an inline `{"type": "string", "format": "date-time"}` schema (#29)
 
 ### FSharp.Data.JsonSchema.NJsonSchema 3.1.0
 

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

@@ -80,7 +80,7 @@ type FSharpSchemaTransformer(config: SchemaGeneratorConfig) =
         member _.TransformAsync(schema, context, _cancellationToken) =
             let ty = context.JsonTypeInfo.Type
             if isFSharpType ty then
-                let doc = SchemaAnalyzer.analyze config ty
+                let doc = SchemaAnalyzer.analyze config ty |> OpenApiSchemaTranslator.inlineFormatOnlyDefinitions
 #if NET10_0_OR_GREATER
                 let rootTypeId = config.TypeIdResolver ty
                 let (translatedRoot, _componentSchemas) =

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

@@ -105,6 +105,50 @@ module OpenApiSchemaTranslator =
         schema
 #endif
 
+    // ── Format-only definition inlining ──
+
+    let rec private inlineNode (inlineable: Map<string, SchemaNode>) (node: SchemaNode) : SchemaNode =
+        match node with
+        | SchemaNode.Ref typeId ->
+            match Map.tryFind typeId inlineable with
+            | Some prim -> prim
+            | None -> node
+        | SchemaNode.Object obj ->
+            SchemaNode.Object
+                { obj with
+                    Properties = obj.Properties |> List.map (fun p -> { p with Schema = inlineNode inlineable p.Schema }) }
+        | SchemaNode.Array items -> SchemaNode.Array(inlineNode inlineable items)
+        | SchemaNode.AnyOf schemas -> SchemaNode.AnyOf(schemas |> List.map (inlineNode inlineable))
+        | SchemaNode.OneOf(schemas, discriminator) -> SchemaNode.OneOf(schemas |> List.map (inlineNode inlineable), discriminator)
+        | SchemaNode.Nullable inner -> SchemaNode.Nullable(inlineNode inlineable inner)
+        | SchemaNode.Map valueSchema -> SchemaNode.Map(inlineNode inlineable valueSchema)
+        | SchemaNode.Primitive _
+        | SchemaNode.Enum _
+        | SchemaNode.Const _
+        | SchemaNode.Any -> node
+
+    /// A definition that's just a bare format-annotated primitive (as produced for
+    /// DateTime, Guid, Uri, TimeSpan, etc.) doesn't need its own component schema —
+    /// a $ref to it is a needless indirection that shows up as an extra, oddly-named
+    /// component in the OpenAPI document (see #29). Inline every reference to such a
+    /// definition directly and drop the now-unreferenced definition.
+    let inlineFormatOnlyDefinitions (doc: SchemaDocument) : SchemaDocument =
+        let inlineable =
+            doc.Definitions
+            |> List.choose (fun (key, value) ->
+                match value with
+                | SchemaNode.Primitive _ -> Some(key, value)
+                | _ -> None)
+            |> Map.ofList
+        if Map.isEmpty inlineable then
+            doc
+        else
+            { Root = inlineNode inlineable doc.Root
+              Definitions =
+                doc.Definitions
+                |> List.filter (fun (key, _) -> not (Map.containsKey key inlineable))
+                |> List.map (fun (key, value) -> key, inlineNode inlineable value) }
+
     // ── Core translation ──
 
     /// Shared translation implementation. `rootTypeId` names the component a self-ref

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

@@ -79,9 +79,47 @@ let private hasSchema (root: JsonElement) (name: string) : bool =
         | false, _ -> false
         | true, schemas -> schemas.TryGetProperty name |> fst
 
+/// Matches the exact repro from GitHub issue #29.
+type WeatherForecast =
+    { Date: System.DateTime
+      TemperatureC: int
+      shape: Shape
+      Summary: string option }
+
 [<Tests>]
 let endToEndTests =
     testList "endToEnd" [
+        test "OpenAPI document generation inlines DateTime fields instead of a dangling $ref" {
+            let app =
+                startApp (fun app ->
+                    app.MapGet(
+                        "/weather",
+                        System.Func<WeatherForecast>(fun () ->
+                            { Date = System.DateTime.Now; TemperatureC = 1; shape = Point; Summary = None })
+                    )
+                    |> ignore
+                )
+            try
+                let (status, body) = getOpenApiDocument app
+                Expect.equal status System.Net.HttpStatusCode.OK "200 OK"
+                use jsonDoc = JsonDocument.Parse body
+                let root = jsonDoc.RootElement
+#if NET10_0_OR_GREATER
+                Expect.isFalse (hasSchema root "WeatherForecast.DateTime") "DateTime must not be registered as its own component"
+#endif
+                let dateSchema =
+                    root
+                        .GetProperty("components")
+                        .GetProperty("schemas")
+                        .GetProperty("WeatherForecast")
+                        .GetProperty("properties")
+                        .GetProperty("date")
+                Expect.equal (dateSchema.GetProperty("type").GetString()) "string" "date field inlines as a string"
+                Expect.equal (dateSchema.GetProperty("format").GetString()) "date-time" "date field keeps the date-time format"
+                Expect.isFalse (dateSchema.TryGetProperty("$ref") |> fst) "date field must not be a $ref"
+            finally
+                stopApp app
+        }
         test "OpenAPI document generation succeeds for a discriminated union response" {
             let app = startApp (fun app -> app.MapGet("/shape", System.Func<Shape>(fun () -> Point)) |> ignore)
             try

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

@@ -224,6 +224,69 @@ let definitionsTests =
         }
     ]
 
+[<Tests>]
+let inlineFormatOnlyDefinitionsTests =
+    testList "translator/inlineFormatOnlyDefinitions" [
+        test "a Ref to a bare Primitive definition is inlined and the definition dropped" {
+            let doc = {
+                Root =
+                    SchemaNode.Object {
+                        Properties = [ { Name = "date"; Schema = SchemaNode.Ref "DateTime"; Description = None } ]
+                        Required = [ "date" ]
+                        AdditionalProperties = false
+                        TypeId = None
+                        Description = None
+                        Title = None
+                    }
+                Definitions = [ "DateTime", SchemaNode.Primitive(PrimitiveType.String, Some "date-time") ]
+            }
+            let inlined = OpenApiSchemaTranslator.inlineFormatOnlyDefinitions doc
+            Expect.isEmpty inlined.Definitions "no definitions remain"
+            match inlined.Root with
+            | SchemaNode.Object obj ->
+                match obj.Properties.[0].Schema with
+                | SchemaNode.Primitive(PrimitiveType.String, Some "date-time") -> ()
+                | other -> failtestf "expected inlined Primitive, got %A" other
+            | other -> failtestf "expected Object root, got %A" other
+        }
+
+        test "a Ref to a non-Primitive definition (e.g. a record) is left as a Ref" {
+            let doc = {
+                Root = SchemaNode.Ref "Widget"
+                Definitions = [
+                    "Widget",
+                    SchemaNode.Object {
+                        Properties = []
+                        Required = []
+                        AdditionalProperties = false
+                        TypeId = None
+                        Description = None
+                        Title = None
+                    }
+                ]
+            }
+            let inlined = OpenApiSchemaTranslator.inlineFormatOnlyDefinitions doc
+            Expect.equal inlined.Definitions doc.Definitions "definition preserved"
+            Expect.equal inlined.Root doc.Root "root Ref preserved"
+        }
+
+        test "translating an inlined document produces no dangling component" {
+            let doc = {
+                Root = SchemaNode.Object {
+                    Properties = [ { Name = "id"; Schema = SchemaNode.Ref "Guid"; Description = None } ]
+                    Required = [ "id" ]
+                    AdditionalProperties = false
+                    TypeId = None
+                    Description = None
+                    Title = None
+                }
+                Definitions = [ "Guid", SchemaNode.Primitive(PrimitiveType.String, Some "guid") ]
+            }
+            let (_, components) = translate (OpenApiSchemaTranslator.inlineFormatOnlyDefinitions doc)
+            Expect.isTrue components.IsEmpty "no component schema registered for the inlined primitive"
+        }
+    ]
+
 #if NET10_0_OR_GREATER
 [<Tests>]
 let documentBindingTests =