FreeFoundations · 20 min · Beginner
📦

Structured Output

Map LLM responses directly to Java POJOs

💡

What Is Structured Output?

Simple overview · Real-world examples included

AI normally returns plain text like "The vendor is Acme Corp and the total is $1,234.56". But for real apps, you need that as a proper data structure with separate fields you can save to a database. This topic shows you how to tell the AI "return this exact JSON format" and have Spring AI automatically convert it into a typed Java record. No manual text parsing required. Real example: automatically extract vendor, amount, date and line items from invoice emails.

🎯 What You'll Learn

→Spring AI BeanOutputConverter
→Designing output schemas
→Java records for AI output
→Validation and error handling

🌍 Real-World Use Case

An accounts payable system that automatically extracts vendor, amount, date from emailed invoices

📊 How It Works — Interactive Flowchart

Hover nodes for quick tip · Click to open detail · Press "Run Data Flow" to animate

Click any box to learn what it does
🧑‍💻
Raw Text
Invoice email
Step 1
⚙️
Spring Boot
Your server
Step 2
🌐
AI API
With schema
Step 3
🤖
AI Model
Returns JSON
Step 4
✅
Java Record
Typed object
Step 5

🛠️ Step-by-Step Implementation

Click any step to expand · Check the circle to mark complete · Progress saves in your browser

Implementation ProgressClick ○ to mark a step complete
0 / 6
01
Define output record
▾
💡 WHY AM I DOING THIS?

Java records are perfect for AI output — immutable, concise, auto-generates equals/hashCode.

▶ WHAT HAPPENS IN THIS STEP

Define exactly what fields you want extracted.

📄 FILES TO CREATE / MODIFY
+InvoiceRecord.java
📁 FOLDER STRUCTURE
model/InvoiceRecord.java
💻 CODE EXAMPLE
public record InvoiceRecord(
    String vendor,
    String amount,
    String currency,
    String date,
    String invoiceNumber,
    List<String> lineItems
) {}
⚠ COMMON MISTAKES
⚠Using class instead of record — more boilerplate for no benefit
▶ HOW TO TEST
Compile check: record should compile without explicit constructor
✅ EXPECTED RESULT
Record compiles cleanly with all fields accessible via accessor methods
02
Create BeanOutputConverter
The converter generates the JSON schema from your record and tells the LLM exactly what structure to return
▾
03
Add validation
LLMs sometimes hallucinate fields
▾
04
Build extraction endpoint
Expose the parser as an API so any system can submit invoice text and get structured data
▾
05
Handle conversion failures
LLMs occasionally return malformed JSON
▾
06
Test with real invoices
Real invoices have quirky formats — PDFs converted to text, tables, foreign currencies
▾

✍️ How to Write the Prompt for This Topic

System: "Extract invoice data. Reply ONLY with valid JSON matching this schema: {schema}. No explanation, no markdown, just JSON."

🎯

Job Interview Prep

8 curated questions · 0 / 8 mastered
Click answers, then rate yourself to track progress
LEVEL:

💡 Don't memorise answers word-for-word. Understand the concept, then explain it in your own words using a real example from this topic's project — that's what impresses interviewers.

⚡ Live AI Demo

LIVE AI DEMO — CLAUDE HAIKUSign up for 3 free demos/day
0/500

📦 Clone & Run the Sample Project

📦
github.com / ai-dev-academy / ai-dev-academy-projects

04-structured-output

Invoice Parser — extracts structured fields from invoice text

Spring Boot 3.xSpring AIJacksonJava Records
⚡QUICK START — RUN IN 5 STEPS
1
Clone the full repo
git clone https://github.com/ai-dev-academy/ai-dev-academy-projects.git
2
Enter the topic folder
cd ai-dev-academy-projects/04-structured-output
3
Set up your API key
cp .env.example .env
# Then open .env and add your API key
4
Run the project
mvn spring-boot:run
5
Test the endpoint
curl -X POST http://localhost:8080/ai/chat \
  -H "Content-Type: application/json" \
  -d '"Hello, what is Structured Output?"'
OPEN IN YOUR IDE
← DashboardAll Topics →