Rename useJsonSchema parameter (#6394)

* Rename useJsonSchema parameter

The `GetResponseAsync<T>` methods accept a `bool?` parameter currently called `useJsonSchema`. This is confusing, because the whole point of the method is to create and use a JSON schema from the `T`. The parameter actually controls _how_ that schema is used, whether it's included as part of the messages (false), as part of a ChatResponseFormat in the ChatOptions (true), or up to the system to decide.

I've clarified it by renaming it from `useJsonSchema` to `useJsonSchemaResponseFormat`. It's wordier, but it disambiguates the intent.

* Update src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientStructuredOutputExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

---------

Co-authored-by: Eirik Tsarpalis <[email protected]>

Author: 2 people

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/ChatClientStructuredOutputExtensions.cs

@@ -33,7 +33,7 @@ public static class ChatClientStructuredOutputExtensions
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="messages">The chat content to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
     /// </param>
@@ -44,19 +44,17 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
         this IChatClient chatClient,
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        GetResponseAsync<T>(chatClient, messages, AIJsonUtilities.DefaultOptions, options, useJsonSchema, cancellationToken);
+        GetResponseAsync<T>(chatClient, messages, AIJsonUtilities.DefaultOptions, options, useJsonSchemaResponseFormat, cancellationToken);
 
     /// <summary>Sends a user chat text message, requesting a response matching the type <typeparamref name="T"/>.</summary>
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="chatMessage">The text content for the chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
-    /// If not specified, the default value is determined by the implementation.
-    /// If a specific value is required, it must be specified by the caller.
     /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
@@ -66,15 +64,15 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
         this IChatClient chatClient,
         string chatMessage,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        GetResponseAsync<T>(chatClient, new ChatMessage(ChatRole.User, chatMessage), options, useJsonSchema, cancellationToken);
+        GetResponseAsync<T>(chatClient, new ChatMessage(ChatRole.User, chatMessage), options, useJsonSchemaResponseFormat, cancellationToken);
 
     /// <summary>Sends a chat message, requesting a response matching the type <typeparamref name="T"/>.</summary>
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="chatMessage">The chat message to send.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
     /// </param>
@@ -85,16 +83,16 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
         this IChatClient chatClient,
         ChatMessage chatMessage,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        GetResponseAsync<T>(chatClient, [chatMessage], options, useJsonSchema, cancellationToken);
+        GetResponseAsync<T>(chatClient, [chatMessage], options, useJsonSchemaResponseFormat, cancellationToken);
 
     /// <summary>Sends a user chat text message, requesting a response matching the type <typeparamref name="T"/>.</summary>
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="chatMessage">The text content for the chat message to send.</param>
     /// <param name="serializerOptions">The JSON serialization options to use.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
     /// </param>
@@ -106,16 +104,16 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
         string chatMessage,
         JsonSerializerOptions serializerOptions,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        GetResponseAsync<T>(chatClient, new ChatMessage(ChatRole.User, chatMessage), serializerOptions, options, useJsonSchema, cancellationToken);
+        GetResponseAsync<T>(chatClient, new ChatMessage(ChatRole.User, chatMessage), serializerOptions, options, useJsonSchemaResponseFormat, cancellationToken);
 
     /// <summary>Sends a chat message, requesting a response matching the type <typeparamref name="T"/>.</summary>
     /// <param name="chatClient">The <see cref="IChatClient"/>.</param>
     /// <param name="chatMessage">The chat message to send.</param>
     /// <param name="serializerOptions">The JSON serialization options to use.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
     /// </param>
@@ -127,16 +125,16 @@ public static Task<ChatResponse<T>> GetResponseAsync<T>(
         ChatMessage chatMessage,
         JsonSerializerOptions serializerOptions,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        GetResponseAsync<T>(chatClient, [chatMessage], serializerOptions, options, useJsonSchema, cancellationToken);
+        GetResponseAsync<T>(chatClient, [chatMessage], serializerOptions, options, useJsonSchemaResponseFormat, cancellationToken);
 
     /// <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>
     /// <param name="serializerOptions">The JSON serialization options to use.</param>
     /// <param name="options">The chat options to configure the request.</param>
-    /// <param name="useJsonSchema">
+    /// <param name="useJsonSchemaResponseFormat">
     /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
     /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
     /// </param>
@@ -149,7 +147,7 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
         IEnumerable<ChatMessage> messages,
         JsonSerializerOptions serializerOptions,
         ChatOptions? options = null,
-        bool? useJsonSchema = null,
+        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default)
     {
         _ = Throw.IfNull(chatClient);
@@ -192,8 +190,8 @@ public static async Task<ChatResponse<T>> GetResponseAsync<T>(
 
         // We default to assuming that models support JSON schema because developers will normally use
         // GetResponseAsync<T> only with models that do. If the model doesn't support JSON schema, it may
-        // throw or it may ignore the schema. In these cases developers should pass useJsonSchema: false.
-        if (useJsonSchema.GetValueOrDefault(true))
+        // throw or it may ignore the schema. In these cases developers should pass useJsonSchemaResponseFormat: false.
+        if (useJsonSchemaResponseFormat ?? true)
         {
             // 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.

test/Libraries/Microsoft.Extensions.AI.Integration.Tests/ChatClientIntegrationTests.cs

@@ -942,7 +942,7 @@ public virtual async Task GetResponseAsync_StructuredOutput_NonNative()
 
         var response = await captureOutputChatClient.GetResponseAsync<Person>("""
             Supply an object to represent Jimbo Smith from Cardiff.
-            """, useJsonSchema: false);
+            """, useJsonSchemaResponseFormat: false);
 
         Assert.Equal("Jimbo Smith", response.Result.FullName);
         Assert.Contains("Cardiff", response.Result.HomeTown);

test/Libraries/Microsoft.Extensions.AI.Tests/ChatCompletion/ChatClientStructuredOutputExtensionsTests.cs

@@ -139,7 +139,7 @@ public async Task SuccessUsage_NoJsonSchema()
         };
 
         var chatHistory = new List<ChatMessage> { new(ChatRole.User, "Hello") };
-        var response = await client.GetResponseAsync<Animal>(chatHistory, useJsonSchema: false, serializerOptions: JsonContext2.Default.Options);
+        var response = await client.GetResponseAsync<Animal>(chatHistory, useJsonSchemaResponseFormat: false, serializerOptions: JsonContext2.Default.Options);
 
         // The response contains the deserialized result and other response properties
         Assert.Equal(1, response.Result.Id);