Area 01 · LLM · Concept 11 of 20

Structured Outputs

Force the reply into JSON that matches your schema, so your code can parse it every time.

11–20 · Production levelPhase 1 · Weeks 3–6≈ 1 hour

The idea

Code needs data, not prose. Structured outputs make the model return JSON that matches a schema you define: field names, types, required fields and allowed values. Providers support this through a JSON schema setting or by defining a "tool" whose input schema is your output shape.

In Python, define the schema once with Pydantic, send it to the model, and validate the reply with the same class. If validation fails, retry with the error message included. With native structured output modes, failures become rare.

Keep schemas small and descriptive. Field descriptions are instructions the model reads, so "due_date: ISO 8601 date, or null if none is mentioned" is better than "due_date: str".

Why it matters

Every pipeline that extracts, classifies or routes depends on parseable output. It is the bridge between the model and your code.

Words to know

  • JSON SchemaA standard way to describe the shape of JSON data.
  • PydanticA Python library for defining and validating data models.

Try it without code

Extract an invoice

  1. Paste an email into a chat app with the prompt below.
  2. Ask the same thing three times and check the keys never change.
Return only JSON with keys vendor (string), total (number), currency (3-letter code), due_date (YYYY-MM-DD or null).

Use it in code

Use a tool schema generated from Pydantic, then validate.

python
from pydantic import BaseModel, Field
import anthropic

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str = Field(description="3-letter ISO code")
    due_date: str | None = Field(description="YYYY-MM-DD or null")

client = anthropic.Anthropic()
email = "Hi, Bluefin Ltd here. Invoice #88 for EUR 1,240.50 is due on 3 March 2027."
msg = client.messages.create(
    model="claude-haiku-5-5", max_tokens=300,
    tools=[{"name": "save_invoice", "description": "Save invoice fields",
            "input_schema": Invoice.model_json_schema()}],
    tool_choice={"type": "tool", "name": "save_invoice"},
    messages=[{"role": "user", "content": email}],
)
invoice = Invoice.model_validate(msg.content[0].input)
print(invoice)
PRACTICE · TICK IT AFTER THIS

Add a /json mode to your chatbot that returns a validated object, and write a retry that resends the validation error once.

Common mistakes

  • Parsing JSON from free text with regex.
  • Huge nested schemas the model struggles to fill.
  • Not validating, then crashing on a missing field.

Go deeper