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".
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
- Paste an email into a chat app with the prompt below.
- Ask the same thing three times and check the keys never change.
Use it in code
Use a tool schema generated from Pydantic, then validate.
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)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.