What is structured output in Spring AI and how does it work internally?

Structured output is Spring AI's capability to have an LLM return JSON that is automatically deserialised into a Java object — a record, POJO, List, or Map — without writing any parsing code yourself. It solves the problem of extracting machine-readable data from natural language model responses.

Internally, Spring AI uses a BeanOutputConverter that does two things in sequence. First it inspects the target Java type and generates a JSON Schema description, then appends instructions to the prompt telling the model to respond in that exact JSON structure. When the model responds, the converter uses Jackson to deserialise the JSON text into the target type.

record BookSummary(String title, String author, int year, String oneLinePlot) {}

BookSummary summary = chatClient.prompt()
    .user("Summarise the book 1984 by George Orwell as structured data.")
    .call()
    .entity(BookSummary.class);

System.out.println(summary.title());     // 1984
System.out.println(summary.author());    // George Orwell

For generic collections use ParameterizedTypeReference:

List<String> languages = chatClient.prompt()
    .user("List five JVM languages")
    .call()
    .entity(new ParameterizedTypeReference<List<String>>() {});

Important caveat: LLMs occasionally produce malformed JSON despite the instructions. Wrap calls in try/catch and consider a retry with a stricter prompt on parse failure. Providers that support a native JSON mode (OpenAI's response_format: json_object, Anthropic tool use) increase reliability when activated through ChatOptions.