feat: Add native structured output support for ChatClient

Implement StructuredOutputChatOptions interface to provide unified structured output
support across AI providers. This enables AI models that provide built-in structured
output to natively generate JSON responses that conform to a specified schema
without additional prompt engineering.

Models that provide structured response should implement the StructuredOutputChatOptions.
To activate the native over the ChatClient prompt-based structured output response**,**
you need to add the AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT advisor parameter to your
ChatClient configuration.

- Add StructuredOutputChatOptions interface with getOutputSchema/setOutputSchema methods
- Implement interface in AnthropicChatOptions, OpenAiChatOptions, and VertexAiGeminiChatOptions
- Update AnthropicApi to support output_format parameter and add structured-outputs-2025-11-13 beta version
- Add ChatClientAttributes for STRUCTURED_OUTPUT_SCHEMA and STRUCTURED_OUTPUT_NATIVE
- Enhance ChatModelCallAdvisor to set output schema when native structured output is enabled
- Update DefaultChatClient to handle native structured output via context attributes
- Configure BeanOutputConverter to mark all fields as required in generated JSON schemas
- Add AdvisorParams.WITH_NATIVE_STRUCTURED_OUTPUT for easy activation via ChatClient
- Add integration tests for native structured output across all three providers

Fixes #4889
Addresses #4463
Part of #2787

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Add documentation

feat: add structured output support to Google GenAI chat model

- Implement StructuredOutputChatOptions interface in GoogleGenAiChatOptions
- Add responseSchema field and related getter/setter methods
- Add outputSchema bridge methods for unified Spring AI API
- Update GoogleGenAiChatModel to handle responseSchema configuration
- Add integration tests for both native and unified structured output APIs
- Include tests for ChatClient with native structured output advisor
- Update VertexAI Gemini tests with consistent naming and structured output support

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Author: tzolov

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java

@@ -32,8 +32,11 @@
 
 import org.springframework.ai.anthropic.api.AnthropicApi;
 import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest;
+import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest.OutputFormat;
 import org.springframework.ai.anthropic.api.AnthropicCacheOptions;
 import org.springframework.ai.anthropic.api.CitationDocument;
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.ai.model.tool.StructuredOutputChatOptions;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.tool.ToolCallback;
 import org.springframework.lang.Nullable;
@@ -51,7 +54,7 @@
  * @since 1.0.0
  */
 @JsonInclude(Include.NON_NULL)
-public class AnthropicChatOptions implements ToolCallingChatOptions {
+public class AnthropicChatOptions implements ToolCallingChatOptions, StructuredOutputChatOptions {
 
 	// @formatter:off
 	private @JsonProperty("model") String model;
@@ -115,6 +118,11 @@ public void setCacheOptions(AnthropicCacheOptions cacheOptions) {
 	@JsonIgnore
 	private Map<String, String> httpHeaders = new HashMap<>();
 
+	/**
+	 * The desired response format for structured output.
+	 */
+	private @JsonProperty("output_format") OutputFormat outputFormat;
+
 	/**
 	 * Container for Claude Skills to make available in this request.
 	 * Skills are collections of instructions, scripts, and resources that
@@ -150,6 +158,7 @@ public static AnthropicChatOptions fromOptions(AnthropicChatOptions fromOptions)
 			.cacheOptions(fromOptions.getCacheOptions())
 			.citationDocuments(fromOptions.getCitationDocuments() != null
 					? new ArrayList<>(fromOptions.getCitationDocuments()) : null)
+			.outputFormat(fromOptions.getOutputFormat())
 			.skillContainer(fromOptions.getSkillContainer())
 			.build();
 	}
@@ -343,6 +352,27 @@ public void validateCitationConsistency() {
 		}
 	}
 
+	public OutputFormat getOutputFormat() {
+		return this.outputFormat;
+	}
+
+	public void setOutputFormat(OutputFormat outputFormat) {
+		Assert.notNull(outputFormat, "outputFormat cannot be null");
+		this.outputFormat = outputFormat;
+	}
+
+	@Override
+	@JsonIgnore
+	public String getOutputSchema() {
+		return this.getOutputFormat() != null ? ModelOptionsUtils.toJsonString(this.getOutputFormat().schema()) : null;
+	}
+
+	@Override
+	@JsonIgnore
+	public void setOutputSchema(String outputSchema) {
+		this.setOutputFormat(new OutputFormat(outputSchema));
+	}
+
 	@Override
 	@SuppressWarnings("unchecked")
 	public AnthropicChatOptions copy() {
@@ -369,6 +399,7 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.toolContext, that.toolContext)
 				&& Objects.equals(this.httpHeaders, that.httpHeaders)
 				&& Objects.equals(this.cacheOptions, that.cacheOptions)
+				&& Objects.equals(this.outputFormat, that.outputFormat)
 				&& Objects.equals(this.citationDocuments, that.citationDocuments)
 				&& Objects.equals(this.skillContainer, that.skillContainer);
 	}
@@ -378,7 +409,7 @@ public int hashCode() {
 		return Objects.hash(this.model, this.maxTokens, this.metadata, this.stopSequences, this.temperature, this.topP,
 				this.topK, this.toolChoice, this.thinking, this.toolCallbacks, this.toolNames,
 				this.internalToolExecutionEnabled, this.toolContext, this.httpHeaders, this.cacheOptions,
-				this.citationDocuments, this.skillContainer);
+				this.outputFormat, this.citationDocuments, this.skillContainer);
 	}
 
 	public static final class Builder {
@@ -520,6 +551,16 @@ public Builder addCitationDocument(CitationDocument document) {
 			return this;
 		}
 
+		public Builder outputFormat(OutputFormat outputFormat) {
+			this.options.outputFormat = outputFormat;
+			return this;
+		}
+
+		public Builder outputSchema(String outputSchema) {
+			this.options.setOutputSchema(outputSchema);
+			return this;
+		}
+
 		/**
 		 * Set the Skills container for this request.
 		 * @param skillContainer Container with skills to make available

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicApi.java

@@ -86,7 +86,7 @@ public static Builder builder() {
 
 	public static final String DEFAULT_ANTHROPIC_VERSION = "2023-06-01";
 
-	public static final String DEFAULT_ANTHROPIC_BETA_VERSION = "tools-2024-04-04,pdfs-2024-09-25";
+	public static final String DEFAULT_ANTHROPIC_BETA_VERSION = "tools-2024-04-04,pdfs-2024-09-25,structured-outputs-2025-11-13";
 
 	public static final String BETA_EXTENDED_CACHE_TTL = "extended-cache-ttl-2025-04-11";
 
@@ -202,7 +202,7 @@ public ResponseEntity<ChatCompletionResponse> chatCompletionEntity(ChatCompletio
 	 * @return Returns a {@link Flux} stream from chat completion chunks.
 	 */
 	public Flux<ChatCompletionResponse> chatCompletionStream(ChatCompletionRequest chatRequest) {
-		return chatCompletionStream(chatRequest, new LinkedMultiValueMap<>());
+		return chatCompletionStream(chatRequest, new HttpHeaders());
 	}
 
 	/**
@@ -837,19 +837,20 @@ public record ChatCompletionRequest(
 		@JsonProperty("tools") List<Tool> tools,
 		@JsonProperty("tool_choice") ToolChoice toolChoice,
 		@JsonProperty("thinking") ThinkingConfig thinking,
+		@JsonProperty("output_format") OutputFormat outputFormat,
 		@JsonProperty("container") SkillContainer container) {
 		// @formatter:on
 
 		public ChatCompletionRequest(String model, List<AnthropicMessage> messages, Object system, Integer maxTokens,
 				Double temperature, Boolean stream) {
 			this(model, messages, system, maxTokens, null, null, stream, temperature, null, null, null, null, null,
-					null);
+					null, null);
 		}
 
 		public ChatCompletionRequest(String model, List<AnthropicMessage> messages, Object system, Integer maxTokens,
 				List<String> stopSequences, Double temperature, Boolean stream) {
 			this(model, messages, system, maxTokens, null, stopSequences, stream, temperature, null, null, null, null,
-					null, null);
+					null, null, null);
 		}
 
 		public static ChatCompletionRequestBuilder builder() {
@@ -860,6 +861,15 @@ public static ChatCompletionRequestBuilder from(ChatCompletionRequest request) {
 			return new ChatCompletionRequestBuilder(request);
 		}
 
+		@JsonInclude(Include.NON_NULL)
+		public record OutputFormat(@JsonProperty("type") String type,
+				@JsonProperty("schema") Map<String, Object> schema) {
+
+			public OutputFormat(String jsonSchema) {
+				this("json_schema", ModelOptionsUtils.jsonToMap(jsonSchema));
+			}
+		}
+
 		/**
 		 * Metadata about the request.
 		 *
@@ -929,6 +939,8 @@ public static final class ChatCompletionRequestBuilder {
 
 		private SkillContainer container;
 
+		private ChatCompletionRequest.OutputFormat outputFormat;
+
 		private ChatCompletionRequestBuilder() {
 		}
 
@@ -947,6 +959,7 @@ private ChatCompletionRequestBuilder(ChatCompletionRequest request) {
 			this.toolChoice = request.toolChoice;
 			this.thinking = request.thinking;
 			this.container = request.container;
+			this.outputFormat = request.outputFormat;
 		}
 
 		public ChatCompletionRequestBuilder model(ChatModel model) {
@@ -1036,10 +1049,15 @@ public ChatCompletionRequestBuilder skills(List<Skill> skills) {
 			return this;
 		}
 
+		public ChatCompletionRequestBuilder outputFormat(ChatCompletionRequest.OutputFormat outputFormat) {
+			this.outputFormat = outputFormat;
+			return this;
+		}
+
 		public ChatCompletionRequest build() {
 			return new ChatCompletionRequest(this.model, this.messages, this.system, this.maxTokens, this.metadata,
 					this.stopSequences, this.stream, this.temperature, this.topP, this.topK, this.tools,
-					this.toolChoice, this.thinking, this.container);
+					this.toolChoice, this.thinking, this.outputFormat, this.container);
 		}
 
 	}

models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/client/AnthropicChatClientIT.java

@@ -35,6 +35,7 @@
 import org.springframework.ai.anthropic.AnthropicTestConfiguration;
 import org.springframework.ai.anthropic.api.AnthropicApi;
 import org.springframework.ai.anthropic.api.tool.MockWeatherService;
+import org.springframework.ai.chat.client.AdvisorParams;
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
 import org.springframework.ai.chat.model.ChatModel;
@@ -118,6 +119,25 @@ void listOutputConverterBean() {
 		assertThat(actorsFilms).hasSize(2);
 	}
 
+	@Test
+	void listOutputConverterBean2() {
+
+		// @formatter:off
+		List<ActorsFilms> actorsFilms = ChatClient.create(this.chatModel).prompt()
+				.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
+				.options(AnthropicChatOptions.builder()
+					.model(AnthropicApi.ChatModel.CLAUDE_SONNET_4_5)
+					.build())
+				.user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
+				.call()
+				.entity(new ParameterizedTypeReference<>() {
+				});
+		// @formatter:on
+
+		logger.info("" + actorsFilms);
+		assertThat(actorsFilms).hasSize(2);
+	}
+
 	@Test
 	void customOutputConverter() {
 

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatModel.java

@@ -748,6 +748,9 @@ GeminiRequest createGeminiRequest(Prompt prompt) {
 		if (requestOptions.getResponseMimeType() != null) {
 			configBuilder.responseMimeType(requestOptions.getResponseMimeType());
 		}
+		if (requestOptions.getResponseSchema() != null) {
+			configBuilder.responseJsonSchema(jsonToSchema(requestOptions.getResponseSchema()));
+		}
 		if (requestOptions.getFrequencyPenalty() != null) {
 			configBuilder.frequencyPenalty(requestOptions.getFrequencyPenalty().floatValue());
 		}

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatOptions.java

@@ -33,6 +33,7 @@
 import org.springframework.ai.google.genai.GoogleGenAiChatModel.ChatModel;
 import org.springframework.ai.google.genai.common.GoogleGenAiSafetySetting;
 import org.springframework.ai.google.genai.common.GoogleGenAiThinkingLevel;
+import org.springframework.ai.model.tool.StructuredOutputChatOptions;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
 import org.springframework.ai.tool.ToolCallback;
 import org.springframework.lang.Nullable;
@@ -50,7 +51,7 @@
  * @since 1.0.0
  */
 @JsonInclude(Include.NON_NULL)
-public class GoogleGenAiChatOptions implements ToolCallingChatOptions {
+public class GoogleGenAiChatOptions implements ToolCallingChatOptions, StructuredOutputChatOptions {
 
 	// https://cloud.google.com/vertex-ai/docs/reference/rest/v1/GenerationConfig
 
@@ -98,6 +99,11 @@ public class GoogleGenAiChatOptions implements ToolCallingChatOptions {
 	 */
 	private @JsonProperty("responseMimeType") String responseMimeType;
 
+	/**
+	 * Optional. Geminie response schema.
+	 */
+	private @JsonProperty("responseSchema") String responseSchema;
+
 	/**
 	 * Optional. Frequency penalties.
 	 */
@@ -220,8 +226,8 @@ public static GoogleGenAiChatOptions fromOptions(GoogleGenAiChatOptions fromOpti
 		options.setModel(fromOptions.getModel());
 		options.setToolCallbacks(fromOptions.getToolCallbacks());
 		options.setResponseMimeType(fromOptions.getResponseMimeType());
+		options.setResponseSchema(fromOptions.getResponseSchema());
 		options.setToolNames(fromOptions.getToolNames());
-		options.setResponseMimeType(fromOptions.getResponseMimeType());
 		options.setGoogleSearchRetrieval(fromOptions.getGoogleSearchRetrieval());
 		options.setSafetySettings(fromOptions.getSafetySettings());
 		options.setInternalToolExecutionEnabled(fromOptions.getInternalToolExecutionEnabled());
@@ -318,6 +324,14 @@ public void setResponseMimeType(String mimeType) {
 		this.responseMimeType = mimeType;
 	}
 
+	public String getResponseSchema() {
+		return this.responseSchema;
+	}
+
+	public void setResponseSchema(String responseSchema) {
+		this.responseSchema = responseSchema;
+	}
+
 	@Override
 	public List<ToolCallback> getToolCallbacks() {
 		return this.toolCallbacks;
@@ -472,6 +486,18 @@ public void setToolContext(Map<String, Object> toolContext) {
 		this.toolContext = toolContext;
 	}
 
+	@Override
+	public String getOutputSchema() {
+		return this.getResponseSchema();
+	}
+
+	@Override
+	@JsonIgnore
+	public void setOutputSchema(String jsonSchemaText) {
+		this.setResponseSchema(jsonSchemaText);
+		this.setResponseMimeType("application/json");
+	}
+
 	@Override
 	public boolean equals(Object o) {
 		if (this == o) {
@@ -491,6 +517,7 @@ public boolean equals(Object o) {
 				&& this.thinkingLevel == that.thinkingLevel
 				&& Objects.equals(this.maxOutputTokens, that.maxOutputTokens) && Objects.equals(this.model, that.model)
 				&& Objects.equals(this.responseMimeType, that.responseMimeType)
+				&& Objects.equals(this.responseSchema, that.responseSchema)
 				&& Objects.equals(this.toolCallbacks, that.toolCallbacks)
 				&& Objects.equals(this.toolNames, that.toolNames)
 				&& Objects.equals(this.safetySettings, that.safetySettings)
@@ -501,10 +528,10 @@ public boolean equals(Object o) {
 	@Override
 	public int hashCode() {
 		return Objects.hash(this.stopSequences, this.temperature, this.topP, this.topK, this.candidateCount,
-				this.frequencyPenalty, this.presencePenalty, this.thinkingBudget, this.includeThoughts,
-				this.thinkingLevel, this.maxOutputTokens, this.model, this.responseMimeType, this.toolCallbacks,
-				this.toolNames, this.googleSearchRetrieval, this.safetySettings, this.internalToolExecutionEnabled,
-				this.toolContext, this.labels);
+				this.frequencyPenalty, this.presencePenalty, this.includeThoughts, this.thinkingLevel,
+				this.thinkingBudget, this.maxOutputTokens, this.model, this.responseMimeType, this.responseSchema,
+				this.toolCallbacks, this.toolNames, this.googleSearchRetrieval, this.safetySettings,
+				this.internalToolExecutionEnabled, this.toolContext, this.labels);
 	}
 
 	@Override
@@ -591,6 +618,16 @@ public Builder responseMimeType(String mimeType) {
 			return this;
 		}
 
+		public Builder responseSchema(String responseSchema) {
+			this.options.setResponseSchema(responseSchema);
+			return this;
+		}
+
+		public Builder outputSchema(String jsonSchema) {
+			this.options.setOutputSchema(jsonSchema);
+			return this;
+		}
+
 		public Builder toolCallbacks(List<ToolCallback> toolCallbacks) {
 			this.options.toolCallbacks = toolCallbacks;
 			return this;