Make all response format models internal (#32005)

specification/ai/ModelClient/client.tsp

@@ -16,17 +16,20 @@ namespace Customizations; // The actual name here doesn't matter and is here for
 @@usage(AI.Model.StreamingChatResponseMessageUpdate, Usage.output);
 @@usage(AI.Model.StreamingChatResponseToolCallUpdate, Usage.output);
 
-// Since we made all operator methods internal, we need to expliclty
-// say we still want the models they use to be public.
+// The operators need to be hidden, since we hand-write the public versions of those
+@@access(AI.Model.getChatCompletions, Access.internal);
+@@access(AI.Model.getEmbeddings, Access.internal);
+@@access(AI.Model.getImageEmbeddings, Access.internal);
+@@access(AI.Model.getModelInfo, Access.internal, "python");
+
+// Since we made all operator methods internal, we need to explicity
+// say we still want the models they use to be public, since they will be used by hand-written operator methods.
 @@access(AI.Model.ChatChoice, Access.public);
 @@access(AI.Model.ChatCompletions, Access.public);
 @@access(AI.Model.ChatCompletionsToolCall, Access.public);
 @@access(AI.Model.ChatCompletionsToolDefinition, Access.public);
 @@access(AI.Model.ChatCompletionsNamedToolChoice, Access.public);
 @@access(AI.Model.ChatCompletionsNamedToolChoiceFunction, Access.public);
-@@access(AI.Model.ChatCompletionsResponseFormat, Access.public);
-@@access(AI.Model.ChatCompletionsResponseFormatJsonObject, Access.public);
-@@access(AI.Model.ChatCompletionsResponseFormatText, Access.public);
 @@access(AI.Model.ChatCompletionsToolCall, Access.public);
 @@access(AI.Model.ChatCompletionsToolDefinition, Access.public);
 @@access(AI.Model.ChatCompletionsToolChoicePreset, Access.public);
@@ -58,17 +61,14 @@ namespace Customizations; // The actual name here doesn't matter and is here for
 @@access(AI.Model.StreamingChatChoiceUpdate, Access.public, "python");
 @@access(AI.Model.StreamingChatResponseMessageUpdate, Access.public, "python");
 @@access(AI.Model.StreamingChatResponseToolCallUpdate, Access.public, "python");
+@@access(AI.Model.ChatCompletionsResponseFormatJsonSchemaDefinition,
+  Access.public,
+  "python"
+);
 
-// The operators need to be hidden, since we hand-write the public versions of those
-@@access(AI.Model.getChatCompletions, Access.internal);
-@@access(AI.Model.getEmbeddings, Access.internal);
-@@access(AI.Model.getImageEmbeddings, Access.internal);
-@@access(AI.Model.getModelInfo, Access.internal, "python");
-
-// Hide the JSON schema class in favor of a factory method on the ChatCompletionsResponseFormat class
-@@access(AI.Model.ChatCompletionsResponseFormatJsonSchema,
-  Access.internal,
-  "csharp"
+@@clientName(AI.Model.ChatCompletionsResponseFormatJsonSchemaDefinition,
+  "JsonSchemaFormat",
+  "python"
 );
 
 // We use shorter names in the Python client library

specification/ai/ModelClient/models/chat_completions.tsp

@@ -266,22 +266,32 @@ model ChatCompletionsResponseFormatJsonObject
 }
 
 @doc("""
-  The definition of the required JSON schema in the response, and associated metadata.
+  Defines the response format for chat completions as JSON with a given schema. The AI model
+  will need to adhere to this schema when generating completions.
   """)
 model ChatCompletionsResponseFormatJsonSchemaDefinition {
-  /** The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. */
+  @doc("""
+    A name that labels this JSON schema. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
+    """)
   name: string;
 
-  /** The definition of the JSON schema */
+  @doc("""
+    The definition of the JSON schema. See https://json-schema.org/overview/what-is-jsonschema.
+    Note that AI models usually only support a subset of the keywords defined by JSON schema. Consult your AI model documentation
+    to determine what is supported.
+    """)
   schema: Record<unknown>;
 
-  /** A description of the response format, used by the AI model to determine how to generate responses in this format. */
+  @doc("""
+    A description of the response format, used by the AI model to determine how to generate responses in this format.
+    """)
   description?: string;
 
   @doc("""
-    Whether to enable strict schema adherence when generating the output.
-    If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of
-    JSON Schema is supported when `strict` is `true`.
+    If set to true, the service will error out if the provided JSON schema contains keywords
+    not supported by the AI model. An example of such keyword may be `maxLength` for JSON type `string`.
+    If false, and the provided JSON schema contains keywords not supported
+    by the AI model, the AI model will not error out. Instead it will ignore the unsupported keywords.
     """)
   strict?: boolean = false;
 }

specification/ai/data-plane/AI.Model/preview/2024-05-01-preview/openapi.json

@@ -688,15 +688,15 @@
     },
     "ChatCompletionsResponseFormatJsonSchemaDefinition": {
       "type": "object",
-      "description": "The definition of the required JSON schema in the response, and associated metadata.",
+      "description": "Defines the response format for chat completions as JSON with a given schema. The AI model\nwill need to adhere to this schema when generating completions.",
       "properties": {
         "name": {
           "type": "string",
-          "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."
+          "description": "A name that labels this JSON schema. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."
         },
         "schema": {
           "type": "object",
-          "description": "The definition of the JSON schema",
+          "description": "The definition of the JSON schema. See https://json-schema.org/overview/what-is-jsonschema.\nNote that AI models usually only support a subset of the keywords defined by JSON schema. Consult your AI model documentation\nto determine what is supported.",
           "additionalProperties": {}
         },
         "description": {
@@ -705,7 +705,7 @@
         },
         "strict": {
           "type": "boolean",
-          "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of\nJSON Schema is supported when `strict` is `true`.",
+          "description": "If set to true, the service will error out if the provided JSON schema contains keywords\nnot supported by the AI model. An example of such keyword may be `maxLength` for JSON type `string`.\nIf false, and the provided JSON schema contains keywords not supported\nby the AI model, the AI model will not error out. Instead it will ignore the unsupported keywords.",
           "default": false
         }
       },