Skip to content

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

PythonPython not started

Pydantic coerces where it is safe and refuses where it is not:

PythonPython not started

Parsing what the model returned

The realistic entry point is a JSON string of unknown quality:

PythonPython not started

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:

PythonPython not started

Nesting and lists

PythonPython not started

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:

PythonPython not started

Constraining the model

Pydantic can emit the JSON schema, and the API takes that schema and constrains generation to match it:

PythonPython not started

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:

PythonPython not started

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.

PythonPython not started

Try it yourself

Exercise 1

Define Review with sentiment limited to positive/neutral/negative, score between 0 and 1, topics defaulting to an empty list, and an optional reply.

Your turnPython not started
Exercise 2

Write parse_or_repair(raw) returning (review, None) on success, or (None, message) where the message names every failing field.

Your turnPython not started

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_json turns an untrusted string into a typed object or raises.
  • Literal pins a value set, Field(ge=..., le=..., description=...) bounds and documents, and the descriptions reach the model.
  • Use default_factory=list for mutable defaults, and validators for the invariants a type cannot express.
  • Constrain generation with output_config={"format": ...}, or let client.messages.parse() validate for you. The old output_format parameter is deprecated.
  • strict: true on a tool needs additionalProperties: false and a full required list.
  • Validate anyway, and turn the validation error into a repair message. One retry is usually enough.