Add ChatResponseFormat.ForJsonSchema<T>

stephentoub · stephentoub · commit 7386635a52af · 2025-09-09T16:44:41.000-04:00
Moves the implementation used by `GetResponseAsync&lt;T&gt;` to be exposed as its own helper that can be used directly, for cases where folks want the formatting but don't want to use the generic `GetResponseAsync&lt;T&gt;`.
diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs
@@ -1,19 +1,34 @@
 ﻿// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.ComponentModel;
+using System.Reflection;
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using System.Text.RegularExpressions;
 
 namespace Microsoft.Extensions.AI;
 
+#pragma warning disable CA1052 // Static holder types should be Static or NotInheritable
+#pragma warning disable S2333 // gratiutious partial
+
 /// <summary>Represents the response format that is desired by the caller.</summary>
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(ChatResponseFormatText), typeDiscriminator: "text")]
 [JsonDerivedType(typeof(ChatResponseFormatJson), typeDiscriminator: "json")]
-#pragma warning disable CA1052 // Static holder types should be Static or NotInheritable
-public class ChatResponseFormat
-#pragma warning restore CA1052
+public partial class ChatResponseFormat
 {
+    private static readonly AIJsonSchemaCreateOptions _inferenceOptions = new()
+    {
+        IncludeSchemaKeyword = true,
+        TransformOptions = new AIJsonSchemaTransformOptions
+        {
+            DisallowAdditionalProperties = true,
+            RequireAllProperties = true,
+            MoveDefaultKeywordToDescription = true,
+        },
+    };
+
     /// <summary>Initializes a new instance of the <see cref="ChatResponseFormat"/> class.</summary>
     /// <remarks>Prevents external instantiation. Close the inheritance hierarchy for now until we have good reason to open it.</remarks>
     private protected ChatResponseFormat()
@@ -33,7 +48,41 @@ private protected ChatResponseFormat()
     /// <returns>The <see cref="ChatResponseFormatJson"/> instance.</returns>
     public static ChatResponseFormatJson ForJsonSchema(
         JsonElement schema, string? schemaName = null, string? schemaDescription = null) =>
-        new(schema,
-            schemaName,
-            schemaDescription);
+        new(schema, schemaName, schemaDescription);
+
+    /// <summary>Creates a <see cref="ChatResponseFormatJson"/> representing structured JSON data with the specified schema.</summary>
+    /// <typeparam name="T">The type for which a schema should be exported and used as the response schema.</typeparam>
+    /// <param name="serializerOptions">The JSON serialization options to use.</param>
+    /// <param name="schemaName">An optional name of the schema. By default, this will be inferred from <typeparamref name="T"/>.</param>
+    /// <param name="schemaDescription">An optional description of the schema. An optional name of the schema. By default, this will be inferred from <typeparamref name="T"/>.</param>
+    /// <returns>The <see cref="ChatResponseFormatJson"/> instance.</returns>
+    /// <remarks>
+    /// Many AI services that support structured output require that the JSON schema have a top-level 'type=object'.
+    /// If <typeparamref name="T"/> is a primitive type like <see cref="string"/>, <see cref="int"/>, or <see cref="bool"/>,
+    /// or if it's a type that serializes as a JSON array, attempting to use the resulting schema with such services may fail.
+    /// In such cases, consider instead using a <typeparamref name="T"/> that wraps the actual type in a class or struct so that
+    /// it serializes as a JSON object with the original type as a property of that object.
+    /// </remarks>
+    public static ChatResponseFormatJson ForJsonSchema<T>(
+        JsonSerializerOptions? serializerOptions = null, string? schemaName = null, string? schemaDescription = null)
+    {
+        var schema = AIJsonUtilities.CreateJsonSchema(
+            type: typeof(T),
+            serializerOptions: serializerOptions ?? AIJsonUtilities.DefaultOptions,
+            inferenceOptions: _inferenceOptions);
+
+        return ForJsonSchema(
+            schema,
+            schemaName ?? InvalidNameCharsRegex().Replace(typeof(T).Name, "_"),
+            schemaDescription ?? typeof(T).GetCustomAttribute<DescriptionAttribute>()?.Description);
+    }
+
+    /// <summary>Regex that flags any character other than ASCII digits, ASCII letters, or underscore.</summary>
+#if NET
+    [GeneratedRegex("[^0-9A-Za-z_]")]
+    private static partial Regex InvalidNameCharsRegex();
+#else
+    private static Regex InvalidNameCharsRegex() => _invalidNameCharsRegex;
+    private static readonly Regex _invalidNameCharsRegex = new("[^0-9A-Za-z_]", RegexOptions.Compiled);
+#endif
 }
diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json b/src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json
@@ -1156,6 +1156,10 @@
         {
           "Member": "static Microsoft.Extensions.AI.ChatResponseFormatJson Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema(System.Text.Json.JsonElement schema, string? schemaName = null, string? schemaDescription = null);",
           "Stage": "Stable"
+        },
+        {
+          "Member": "static Microsoft.Extensions.AI.ChatResponseFormatJson Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<T>(System.Text.Json.JsonSerializerOptions? serializerOptions = null, string? schemaName = null, string? schemaDescription = null);",
+          "Stage": "Stable"
         }
       ],
       "Properties": [
diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientStructuredOutputExtensions.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientStructuredOutputExtensions.cs
@@ -3,11 +3,9 @@
 
 using System;
 using System.Collections.Generic;
-using System.ComponentModel;
-using System.Reflection;
+using System.Diagnostics;
 using System.Text.Json;
 using System.Text.Json.Nodes;
-using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Shared.Diagnostics;
@@ -23,17 +21,6 @@ namespace Microsoft.Extensions.AI;
 /// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/structured-output">Request a response with structured output.</related>
 public static partial class ChatClientStructuredOutputExtensions
 {
-    private static readonly AIJsonSchemaCreateOptions _inferenceOptions = new()
-    {
-        IncludeSchemaKeyword = true,
-        TransformOptions = new AIJsonSchemaTransformOptions
-        {
-            DisallowAdditionalProperties = true,
-            RequireAllProperties = true,
-            MoveDefaultKeywordToDescription = true,
-        },
-    };
-
     /// <summary>Sends chat messages, requesting a response matching the type <typeparamref name="T"/>.</summary>
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="messages">The chat content to send.</param>
@@ -161,20 +148,12 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
 
         serializerOptions.MakeReadOnly();
 
-        var schemaElement = AIJsonUtilities.CreateJsonSchema(
-            type: typeof(T),
-            serializerOptions: serializerOptions,
-            inferenceOptions: _inferenceOptions);
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
 
-        bool isWrappedInObject;
-        JsonElement schema;
-        if (SchemaRepresentsObject(schemaElement))
-        {
-            // For object-representing schemas, we can use them as-is
-            isWrappedInObject = false;
-            schema = schemaElement;
-        }
-        else
+        Debug.Assert(responseFormat.Schema is not null, "ForJsonSchema should always populate Schema");
+        var schema = responseFormat.Schema!.Value;
+        bool isWrappedInObject = false;
+        if (!SchemaRepresentsObject(schema))
         {
             // For non-object-representing schemas, we wrap them in an object schema, because all
             // the real LLM providers today require an object schema as the root. This is currently
@@ -184,10 +163,11 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
             {
                 { "$schema", "https://json-schema.org/draft/2020-12/schema" },
                 { "type", "object" },
-                { "properties", new JsonObject { { "data", JsonElementToJsonNode(schemaElement) } } },
+                { "properties", new JsonObject { { "data", JsonElementToJsonNode(schema) } } },
                 { "additionalProperties", false },
                 { "required", new JsonArray("data") },
             }, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(JsonObject)));
+            responseFormat = ChatResponseFormat.ForJsonSchema(schema, responseFormat.SchemaName, responseFormat.SchemaDescription);
         }
 
         ChatMessage? promptAugmentation = null;
@@ -200,10 +180,7 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
         {
             // When using native structured output, we don't add any additional prompt, because
             // the LLM backend is meant to do whatever's needed to explain the schema to the LLM.
-            options.ResponseFormat = ChatResponseFormat.ForJsonSchema(
-                schema,
-                schemaName: SanitizeMemberName(typeof(T).Name),
-                schemaDescription: typeof(T).GetCustomAttribute<DescriptionAttribute>()?.Description);
+            options.ResponseFormat = responseFormat;
         }
         else
         {
@@ -213,7 +190,7 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
             promptAugmentation = new ChatMessage(ChatRole.User, $$"""
                 Respond with a JSON value conforming to the following schema:
                 ```
-                {{schema}}
+                {{responseFormat.Schema}}
                 ```
                 """);
 
@@ -222,53 +199,31 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
 
         var result = await chatClient.GetResponseAsync(messages, options, cancellationToken);
         return new ChatResponse<T>(result, serializerOptions) { IsWrappedInObject = isWrappedInObject };
-    }
 
-    private static bool SchemaRepresentsObject(JsonElement schemaElement)
-    {
-        if (schemaElement.ValueKind is JsonValueKind.Object)
+        static bool SchemaRepresentsObject(JsonElement schemaElement)
         {
-            foreach (var property in schemaElement.EnumerateObject())
+            if (schemaElement.ValueKind is JsonValueKind.Object)
             {
-                if (property.NameEquals("type"u8))
+                foreach (var property in schemaElement.EnumerateObject())
                 {
-                    return property.Value.ValueKind == JsonValueKind.String
-                        && property.Value.ValueEquals("object"u8);
+                    if (property.NameEquals("type"u8))
+                    {
+                        return property.Value.ValueKind == JsonValueKind.String
+                            && property.Value.ValueEquals("object"u8);
+                    }
                 }
             }
-        }
 
-        return false;
-    }
+            return false;
+        }
 
-    private static JsonNode? JsonElementToJsonNode(JsonElement element)
-    {
-        return element.ValueKind switch
-        {
-            JsonValueKind.Null => null,
-            JsonValueKind.Array => JsonArray.Create(element),
-            JsonValueKind.Object => JsonObject.Create(element),
-            _ => JsonValue.Create(element)
-        };
+        static JsonNode? JsonElementToJsonNode(JsonElement element) =>
+            element.ValueKind switch
+            {
+                JsonValueKind.Null => null,
+                JsonValueKind.Array => JsonArray.Create(element),
+                JsonValueKind.Object => JsonObject.Create(element),
+                _ => JsonValue.Create(element)
+            };
     }
-
-    /// <summary>
-    /// Removes characters from a .NET member name that shouldn't be used in an AI function name.
-    /// </summary>
-    /// <param name="memberName">The .NET member name that should be sanitized.</param>
-    /// <returns>
-    /// Replaces non-alphanumeric characters in the identifier with the underscore character.
-    /// Primarily intended to remove characters produced by compiler-generated method name mangling.
-    /// </returns>
-    private static string SanitizeMemberName(string memberName) =>
-        InvalidNameCharsRegex().Replace(memberName, "_");
-
-    /// <summary>Regex that flags any character other than ASCII digits or letters or the underscore.</summary>
-#if NET
-    [GeneratedRegex("[^0-9A-Za-z_]")]
-    private static partial Regex InvalidNameCharsRegex();
-#else
-    private static Regex InvalidNameCharsRegex() => _invalidNameCharsRegex;
-    private static readonly Regex _invalidNameCharsRegex = new("[^0-9A-Za-z_]", RegexOptions.Compiled);
-#endif
 }
diff --git a/test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/ChatCompletion/ChatResponseFormatTests.cs b/test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/ChatCompletion/ChatResponseFormatTests.cs
@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.ComponentModel;
 using System.Text.Json;
 using Xunit;
 
@@ -81,4 +82,76 @@ public void Serialization_ForJsonSchemaRoundtrips()
         Assert.Equal("name", actual.SchemaName);
         Assert.Equal("description", actual.SchemaDescription);
     }
+
+    [Fact]
+    public void ForJsonSchema_PrimitiveType_Succeeds()
+    {
+        ChatResponseFormatJson format = ChatResponseFormat.ForJsonSchema<int>();
+        Assert.NotNull(format);
+        Assert.NotNull(format.Schema);
+        Assert.Equal("""{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"integer"}""", format.Schema.ToString());
+        Assert.Equal("Int32", format.SchemaName);
+        Assert.Null(format.SchemaDescription);
+    }
+
+    [Fact]
+    public void ForJsonSchema_IncludedType_Succeeds()
+    {
+        ChatResponseFormatJson format = ChatResponseFormat.ForJsonSchema<DataContent>();
+        Assert.NotNull(format);
+        Assert.NotNull(format.Schema);
+        Assert.Contains("A data URI representing the content.", format.Schema.ToString());
+        Assert.Equal("DataContent", format.SchemaName);
+        Assert.Null(format.SchemaDescription);
+    }
+
+    [Theory]
+    [InlineData(null, null)]
+    [InlineData("AnotherName", null)]
+    [InlineData(null, "another description")]
+    [InlineData("AnotherName", "another description")]
+    public void ForJsonSchema_ComplexType_Succeeds(string? name, string? description)
+    {
+        ChatResponseFormatJson format = ChatResponseFormat.ForJsonSchema<SomeType>(TestJsonSerializerContext.Default.Options, name, description);
+        Assert.NotNull(format);
+        Assert.Equal(
+            """
+            {
+              "$schema": "https://json-schema.org/draft/2020-12/schema",
+              "description": "abcd",
+              "type": "object",
+              "properties": {
+                "someInteger": {
+                  "description": "efg",
+                  "type": "integer"
+                },
+                "someString": {
+                  "description": "hijk",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "additionalProperties": false,
+              "required": [
+                "someInteger",
+                "someString"
+              ]
+            }
+            """,
+            JsonSerializer.Serialize(format.Schema, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(JsonElement))));
+        Assert.Equal(name ?? "SomeType", format.SchemaName);
+        Assert.Equal(description ?? "abcd", format.SchemaDescription);
+    }
+
+    [Description("abcd")]
+    public class SomeType
+    {
+        [Description("efg")]
+        public int SomeInteger { get; set; }
+
+        [Description("hijk")]
+        public string? SomeString { get; set; }
+    }
 }
diff --git a/test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/TestJsonSerializerContext.cs b/test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/TestJsonSerializerContext.cs
@@ -36,4 +36,5 @@ namespace Microsoft.Extensions.AI;
 [JsonSerializable(typeof(Guid))] // Used in Content tests
 [JsonSerializable(typeof(decimal))] // Used in Content tests
 [JsonSerializable(typeof(HostedMcpServerToolApprovalMode))]
+[JsonSerializable(typeof(ChatResponseFormatTests.SomeType))]
 internal sealed partial class TestJsonSerializerContext : JsonSerializerContext;

Original file line number	Diff line number	Diff line change
`@@ -1156,6 +1156,10 @@`
`1156`	`1156`	`{`
`1157`	`1157`	`"Member": "static Microsoft.Extensions.AI.ChatResponseFormatJson Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema(System.Text.Json.JsonElement schema, string? schemaName = null, string? schemaDescription = null);",`
`1158`	`1158`	`"Stage": "Stable"`
	`1159`	`+ },`
	`1160`	`+ {`
	`1161`	`+ "Member": "static Microsoft.Extensions.AI.ChatResponseFormatJson Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<T>(System.Text.Json.JsonSerializerOptions? serializerOptions = null, string? schemaName = null, string? schemaDescription = null);",`
	`1162`	`+ "Stage": "Stable"`
`1159`	`1163`	`}`
`1160`	`1164`	`],`
`1161`	`1165`	`"Properties": [`