This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

Output Converters

The high-level .entity(…​) API is built on top of the StructuredOutputConverter abstraction. Most applications never use it directly. Use this lower-level API when you need to:

  • parse answers that the built-in converters reject, for example JSON surrounded by explanations;

  • produce a format other than JSON, such as YAML or CSV;

  • use a converter with the low-level ChatModel API.

A converter takes part before and after the model call. Before the call, it supplies format instructions that are added to the prompt. After the call, it turns the text of the answer into an instance of the target type:

Structured output with format instructions The converter adds format instructions, such as a JSON schema, to your request. The chat model answers with text in that format, and the converter turns the text into a Java object. With native structured output, the provider constrains the answer to the schema. Structured output converter Add format instructions Convert text to Java type Your requestuser text Request + format instructionse.g. a JSON schema Chat modelanswers with text Text answer{"name": "Ada", "year": 1815} Java objectPerson(Ada, 1815) With native structured output, the provider constrains the answer to the schema instead of relying on the instructions.
Format instructions ask the model for a format, but cannot force it. Combine converters with schema validation, or use provider-native structured output where the model supports it.

Converters are not used for tool calling, whose arguments are already structured.

Structured Output API

The StructuredOutputConverter interface combines the Spring Converter<String, T> interface with a FormatProvider:

public interface StructuredOutputConverter<T> extends Converter<String, T>, FormatProvider {

	String NO_JSON_SCHEMA = "";

	default String getJsonSchema() {
		return NO_JSON_SCHEMA;
	}
}

public interface FormatProvider {

	String getFormat();
}
  • getFormat() returns the format instructions for the model.

  • convert(String) turns the text of the answer into the target type T.

  • getJsonSchema() returns the JSON schema of the target type, if the converter has one.

For example, MapOutputConverter returns these format instructions:

Your response should be in JSON format.
The data structure for the JSON should match this Java class: java.util.HashMap
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Remove the ```json markdown surrounding the output including the trailing "```".

With the low-level ChatModel API, you add the format instructions to the prompt yourself, usually through a PromptTemplate with a {format} placeholder:

How a converter takes part in a ChatModel call The converter's getFormat() supplies format instructions, which a PromptTemplate adds to your request. The chat model returns a ChatResponse; its text is cleaned by a ResponseTextCleaner and converted into the target type by convert(). Your requestuser text getFormat()format instructions PromptTemplatefills {format} ChatModel.call(...)returns a ChatResponse getText()the answer as text clean(...)ResponseTextCleaner convert(...)returns T Green steps are the methods of the converter; the rest is your code or the model.
StructuredOutputConverter<ActorsFilms> converter = new BeanOutputConverter<>(ActorsFilms.class);

Prompt prompt = PromptTemplate.builder()
	.template("""
		Generate the filmography of 5 movies for {actor}.
		{format}
		""")
	.variables(Map.of("actor", "Tom Hanks", "format", converter.getFormat()))
	.build()
	.create();

String text = chatModel.call(prompt).getResult().getOutput().getText();
ActorsFilms actorsFilms = converter.convert(text);

ChatClient does all of this for you when you call .entity(…​).

The Role of getJsonSchema()

Added in 2.0 as a default method of StructuredOutputConverter, getJsonSchema() lets a converter take part in useProviderStructuredOutput() and validateSchema(). Return the schema of your target type, typically by delegating to a BeanOutputConverter, and both options work. If you leave it at the default, which returns no schema, useProviderStructuredOutput() falls back to the format instructions, and validateSchema() throws an IllegalArgumentException.

Available Converters

The structured output converters StructuredOutputConverter combines FormatProvider and Converter. BeanOutputConverter implements it directly; MapOutputConverter extends AbstractMessageOutputConverter, and ListOutputConverter extends AbstractConversionServiceOutputConverter. BeanOutputConverter cleans the response text with a ResponseTextCleaner; by default a CompositeResponseTextCleaner that applies WhitespaceCleaner, ThinkingTagCleaner, MarkdownCodeBlockCleaner and WhitespaceCleaner again. FormatProvidergetFormat(): String Converter<String, T>convert(String): T StructuredOutputConverter<T>getJsonSchema(): String «abstract»AbstractMessageOutputConverter<T>getMessageConverter() BeanOutputConverter<T>getJsonSchema(): String «abstract»AbstractConversionServiceOutputConverter<T>getConversionService() MapOutputConverterMap<String, Object> ListOutputConverterList<String> ResponseTextCleanerclean(String): String cleans the text WhitespaceCleaner ThinkingTagCleaner MarkdownCodeBlockCleaner CompositeResponseTextCleaner By default, BeanOutputConverter trims the text, removes thinking tags and a markdown code fence, and trims it again.
  • BeanOutputConverter<T> converts the answer into a Java class, a record or a generic type given as a ParameterizedTypeReference. Its format instructions contain a JSON schema of the type, generated according to JSON Schema draft 2020-12. It cleans the text of the answer, see Cleaning the Response, and parses it with a Jackson JsonMapper. This is the converter that .entity(Class) and .entity(ParameterizedTypeReference) use.

  • MapOutputConverter converts the answer into a Map<String, Object>. It extends AbstractMessageOutputConverter, which parses the text with a Spring MessageConverter.

  • ListOutputConverter converts a comma-separated answer into a List<String>. It extends AbstractConversionServiceOutputConverter, which converts the text with a Spring ConversionService.

Cleaning the Response

Models often add something around the JSON they were asked for: a markdown code fence, or the reasoning of a thinking model. Before BeanOutputConverter parses the answer, it passes the text through a ResponseTextCleaner. The default cleaner applies, in this order:

  1. WhitespaceCleaner trims leading and trailing whitespace.

  2. ThinkingTagCleaner removes reasoning blocks, such as <thinking>…​</thinking> (Amazon Nova), <think>…​</think> (Qwen) and <reasoning>…​</reasoning>.

  3. MarkdownCodeBlockCleaner removes a code fence, such as ` ```json `, that surrounds the whole answer.

  4. WhitespaceCleaner trims the result again.

To change the cleaning, pass your own cleaner to the BeanOutputConverter constructor, together with an optional JsonMapper. ResponseTextCleaner has a single method, clean(String), so a lambda will do, and CompositeResponseTextCleaner chains several cleaners. A custom cleaner replaces the default one, so add the default steps you still want.

Using Converters

The following sections show each converter with the ChatClient API and with the low-level ChatModel API. The examples use this record:

record ActorsFilms(String actor, List<String> movies) {
}

Bean Output Converter

With ChatClient:

ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
	.user(u -> u.text("Generate the filmography of 5 movies for {actor}.")
		.param("actor", "Tom Hanks"))
	.call()
	.entity(ActorsFilms.class);

With ChatModel:

BeanOutputConverter<ActorsFilms> converter = new BeanOutputConverter<>(ActorsFilms.class);

Prompt prompt = PromptTemplate.builder()
	.template("""
		Generate the filmography of 5 movies for {actor}.
		{format}
		""")
	.variables(Map.of("actor", "Tom Hanks", "format", converter.getFormat()))
	.build()
	.create();

ActorsFilms actorsFilms = converter.convert(chatModel.call(prompt).getResult().getOutput().getText());

Property Ordering in the Generated Schema

BeanOutputConverter respects the Jackson @JsonPropertyOrder annotation when it generates the schema, for records and for classes:

@JsonPropertyOrder({"actor", "movies"})
record ActorsFilms(String actor, List<String> movies) {
}

Generic Types

Use a ParameterizedTypeReference for generic target types, such as a list of records. With ChatClient:

List<ActorsFilms> actorsFilms = ChatClient.create(chatModel).prompt()
	.user("Generate the filmography of 5 movies for Tom Hanks and Bill Murray.")
	.call()
	.entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});

With ChatModel, pass the same type to the converter:

BeanOutputConverter<List<ActorsFilms>> converter =
	new BeanOutputConverter<>(new ParameterizedTypeReference<List<ActorsFilms>>() {});

The rest is the same as in the previous example.

Map Output Converter

With ChatClient:

Map<String, Object> result = ChatClient.create(chatModel).prompt()
	.user("Provide an array of the numbers from 1 to 9 under the key 'numbers'.")
	.call()
	.entity(new MapOutputConverter());

With ChatModel:

MapOutputConverter converter = new MapOutputConverter();

Prompt prompt = PromptTemplate.builder()
	.template("""
		Provide an array of the numbers from 1 to 9 under the key 'numbers'.
		{format}
		""")
	.variables(Map.of("format", converter.getFormat()))
	.build()
	.create();

Map<String, Object> result = converter.convert(chatModel.call(prompt).getResult().getOutput().getText());

.entity(new ParameterizedTypeReference<Map<String, Object>>() {}) also returns a map, but through BeanOutputConverter, with a JSON schema in the format instructions.

List Output Converter

With ChatClient:

List<String> flavors = ChatClient.create(chatModel).prompt()
	.user(u -> u.text("List five {subject}.")
		.param("subject", "ice cream flavors"))
	.call()
	.entity(new ListOutputConverter());

With ChatModel:

ListOutputConverter converter = new ListOutputConverter();

Prompt prompt = PromptTemplate.builder()
	.template("""
		List five {subject}.
		{format}
		""")
	.variables(Map.of("subject", "ice cream flavors", "format", converter.getFormat()))
	.build()
	.create();

List<String> flavors = converter.convert(chatModel.call(prompt).getResult().getOutput().getText());

Custom Cleaning and Custom Converters

Extracting JSON from Prose

The default cleaner removes a code fence only when the fence surrounds the whole answer. When the model writes an explanation before or after the JSON, the answer still fails to parse:

Here's the filmography:
```json
{ "actor": "Tom Hanks", "movies": ["Forrest Gump", "Cast Away"] }
```

A custom cleaner can cut out the JSON object. This one keeps the removal of reasoning blocks, then takes the text from the first { to the last }:

ResponseTextCleaner extractJson = text -> {
	if (text == null) {
		return null;
	}
	int start = text.indexOf('{');
	int end = text.lastIndexOf('}');
	return (start >= 0 && end > start) ? text.substring(start, end + 1) : text;
};

BeanOutputConverter<ActorsFilms> converter = new BeanOutputConverter<>(ActorsFilms.class, null,
		CompositeResponseTextCleaner.builder()
			.addCleaner(new ThinkingTagCleaner())
			.addCleaner(extractJson)
			.build());

ActorsFilms films = chatClient.prompt()
	.user("Generate the filmography for a random actor.")
	.call()
	.entity(converter);

The converter is still a BeanOutputConverter, so it still has a JSON schema, and validateSchema() and useProviderStructuredOutput() work as with .entity(ActorsFilms.class).

Writing a Converter

To change more than the cleaning, implement StructuredOutputConverter and delegate to a BeanOutputConverter for the parts you keep. Delegate getJsonSchema() as well, so that both options keep working, see The Role of getJsonSchema():

public class AuditingOutputConverter<T> implements StructuredOutputConverter<T> {

	private static final Logger logger = LoggerFactory.getLogger(AuditingOutputConverter.class);

	private final BeanOutputConverter<T> delegate;

	public AuditingOutputConverter(Class<T> type) {
		this.delegate = new BeanOutputConverter<>(type);
	}

	@Override
	public String getFormat() {
		return this.delegate.getFormat();
	}

	@Override
	public String getJsonSchema() {
		return this.delegate.getJsonSchema();
	}

	@Override
	public T convert(String text) {
		logger.debug("Model answer: {}", text);
		return this.delegate.convert(text);
	}
}

Non-JSON Formats

For formats other than JSON, such as YAML for configuration or CSV for extracted data, implement StructuredOutputConverter from scratch: write your own getFormat() instructions and your own convert(…​) parser. Leave getJsonSchema() at its default: the format instructions alone guide the model, also when you call useProviderStructuredOutput(). Do not call validateSchema() with such a converter, because without a schema it throws an IllegalArgumentException.