LLM Engineering·Lesson 47 of 67·advanced
Structured output and schema validation with Pydantic
Stop parsing prose. Declare the shape you need, have the API constrain the model to it, and validate what comes back — because a model's JSON is still untrusted input.
In this lesson · 20 min
- →Define a schema with Pydantic and validate data against it
- →Read a ValidationError and act on it
- →Constrain fields, nest models and add custom validators
- →Generate a JSON schema and use it to constrain the model's output
- →Write a repair loop for the cases that still fail
Asking a model for JSON and hoping is not engineering. Pydantic lets you declare the shape you need, the API can constrain the model to produce it, and validation catches whatever slips through. This lesson is fully runnable — Pydantic is available here.
A schema
Pydantic coerces where it is safe and refuses where it is not:
Parsing what the model returned
The realistic entry point is a JSON string of unknown quality:
The last two are the failures that matter. One is missing a required field; the other wrapped the JSON in prose, which is exactly what a model does when you ask nicely instead of constraining it.
Constraining fields
Types alone are a weak contract. Literal pins a value to a set, Field adds bounds and a
description, and both end up in the schema the model sees:
Nesting and lists
Note default_factory=list — the same mutable-default rule from module 2, enforced here by the
library.
Custom validation
Some rules are not expressible as a type. A validator runs after the field is parsed:
Constraining the model
Pydantic can emit the JSON schema, and the API takes that schema and constrains generation to match it:
On your own machine, the call that uses it:
import anthropic
from pydantic import BaseModel
client = anthropic.Anthropic()
class Ticket(BaseModel):
category: str
urgency: int
summary: str
# messages.parse validates the response against the model for you.
response = client.messages.parse(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "I was charged twice in March"}],
output_config={"format": Ticket},
)
ticket = response.parsed_content # already a Ticket instance
print(ticket.category, ticket.urgency)
The lower-level form passes the schema directly on messages.create:
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "I was charged twice in March"}],
output_config={
"format": {
"type": "json_schema",
"schema": Ticket.model_json_schema(),
}
},
)
The same constraint applies to tool arguments. strict: true on a tool definition guarantees the
input validates against your schema:
tools = [{
"name": "record_ticket",
"description": "Record a classified support ticket.",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"category": {"type": "string", "enum": ["billing", "bug", "docs"]},
"urgency": {"type": "integer", "minimum": 1, "maximum": 5},
},
"required": ["category", "urgency"],
"additionalProperties": False,
},
}]
additionalProperties: false and a complete required list are not optional with strict — the
API rejects a schema without them.
Validate anyway
Constrained generation makes malformed output rare, not impossible — and it says nothing about whether the values make sense. Validate at the boundary regardless:
That second return value is the repair loop: send the validation error back as a user message and ask again. One retry fixes almost everything; a second is rarely worth it.
Try it yourself
Define Review with sentiment limited to positive/neutral/negative, score between 0 and 1, topics defaulting to an empty list, and an optional reply.
Write parse_or_repair(raw) returning (review, None) on success, or (None, message) where the message names every failing field.
Check yourself
The API constrained the output to your JSON schema. Why still validate with Pydantic?
Check yourself
What does `strict: true` on a tool definition require, and what does it guarantee?
Recap
- Declare the shape with Pydantic;
model_validate_jsonturns an untrusted string into a typed object or raises. Literalpins a value set,Field(ge=..., le=..., description=...)bounds and documents, and the descriptions reach the model.- Use
default_factory=listfor mutable defaults, and validators for the invariants a type cannot express. - Constrain generation with
output_config={"format": ...}, or letclient.messages.parse()validate for you. The oldoutput_formatparameter is deprecated. strict: trueon a tool needsadditionalProperties: falseand a fullrequiredlist.- Validate anyway, and turn the validation error into a repair message. One retry is usually enough.