|
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
ChatModelAPI.
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:
| 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 typeT. -
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:
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
-
BeanOutputConverter<T>converts the answer into a Java class, a record or a generic type given as aParameterizedTypeReference. 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 JacksonJsonMapper. This is the converter that.entity(Class)and.entity(ParameterizedTypeReference)use. -
MapOutputConverterconverts the answer into aMap<String, Object>. It extendsAbstractMessageOutputConverter, which parses the text with a SpringMessageConverter. -
ListOutputConverterconverts a comma-separated answer into aList<String>. It extendsAbstractConversionServiceOutputConverter, which converts the text with a SpringConversionService.
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:
-
WhitespaceCleanertrims leading and trailing whitespace. -
ThinkingTagCleanerremoves reasoning blocks, such as<thinking>…</thinking>(Amazon Nova),<think>…</think>(Qwen) and<reasoning>…</reasoning>. -
MarkdownCodeBlockCleanerremoves a code fence, such as ` ```json `, that surrounds the whole answer. -
WhitespaceCleanertrims 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.