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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.