🧱Get Structured Output with Pydantic and JSON Schema
Replace markdown-fenced near-JSON and regex band-aids with a Pydantic schema the API enforces for you. By the end you can convert any ad-hoc prompt to typed output and measure how many parse failures you just deleted.
Phase 1Why 'Return JSON' Fails and What Schemas Fix
See why 'return JSON' fails and what schemas fix
'Return only JSON' is a wish, not a contract
6 minPrompt-only JSON works most of the time, which is exactly why it's dangerous in production.
JSON mode fixes the syntax, not the shape
6 minJSON mode guarantees parseable JSON but says nothing about whether the keys, types, or values match what your code expects.
A Pydantic model is a contract the API enforces for you
7 minDefining a Pydantic model and passing it to a structured-output API moves validation from your code to the API boundary — and gives the model a typed target to aim for.
Validation retry turns a soft failure into a hard fix
6 minWhen a model output fails Pydantic validation, modern libraries automatically re-prompt the model with the validation error — turning a hidden bug into a self-correcting loop.
Phase 2Wiring Pydantic Into Structured Output
Wire Pydantic into JSON mode and structured-output retry
Define your first Pydantic model and watch the schema appear
7 minField types and `Field(...)` constraints translate one-to-one into JSON Schema — what you write in Python is what the model sees.
Make your first structured-output API call
7 minOne library call (`client.beta.chat.completions.parse(...)` or `client.messages.create(...)` with a tool) replaces all your manual parsing — you get a typed object back, not a string.
Trigger a validation failure on purpose
7 minYou can't trust a system you've never seen fail — forcing a validation error is how you confirm the safety net actually catches things.
Steer the model with field descriptions, not extra prompts
6 minField descriptions in the schema beat instructions in the prompt — the model sees the schema as part of the conversation, and a per-field description targets exactly the right place.
Nest models for compound outputs without losing types
7 minPydantic models nest cleanly — a `list[ChildModel]` field gives you typed children, validated end-to-end, with no manual parsing per element.
Phase 3Composing Typed Output With Tools and Agents
Compose typed output with tools, agents, and downstream code
Your LLM-powered classifier is leaking strings into a downstream pipeline
7 minStructured output is the cleanest place to put a typed contract between your LLM step and the rest of your system — without it, type drift propagates silently.
Tool use is structured output wearing a different hat
7 minWhen you give an LLM a tool to call, you're asking it to produce a typed structured output (the tool args) — every tool definition is a schema, and every schema can be a tool.
Schemas double as your test suite for prompt drift
7 minWhen you upgrade the model, change the prompt, or refactor the schema, the validation pass-rate is your regression test — drops in pass-rate localize regressions to the field that started failing.
The schema is the spec — version it like one
7 minWhen your Pydantic models go to production, they become a versioned API contract — between LLM and code, between teams, and between today's data and tomorrow's.
Phase 4Migrating a Real Prompt to Pydantic
Migrate one real prompt to Pydantic and measure the win
Convert one ad-hoc prompt to a Pydantic schema and measure error reduction
18 minConvert one ad-hoc prompt to a Pydantic schema and measure error reduction
Frequently asked questions
- What's the difference between JSON mode and structured output with Pydantic?
- This is covered in the “Get Structured Output with Pydantic and JSON Schema” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- Why does 'return only JSON' in a prompt still fail sometimes?
- This is covered in the “Get Structured Output with Pydantic and JSON Schema” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- Can I use Pydantic with Anthropic Claude or only with OpenAI?
- This is covered in the “Get Structured Output with Pydantic and JSON Schema” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- What happens when the model output fails Pydantic validation?
- This is covered in the “Get Structured Output with Pydantic and JSON Schema” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- How do tool calls relate to structured output schemas?
- This is covered in the “Get Structured Output with Pydantic and JSON Schema” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
Related paths
🐍Python Decorators Introduction
Build one mental model for Python decorators that covers closures, argument passing, functools.wraps, and stacking — then ship a working caching or logging decorator from scratch in under 30 lines.
🦀Rust Lifetimes Explained
Stop reading `'a` as line noise and start reading it as scope arithmetic — one failing snippet at a time — until you can thread lifetimes through a small parser or iterator adapter without fighting the borrow checker.
☸️Kubernetes Core Concepts
Stop drowning in 30+ resource types. Build the mental model one primitive at a time -- pods, deployments, services, ingress, config -- then deploy a real app with rolling updates and health checks.
📈Big O Intuition
Stop treating Big O as math you memorized for an interview — build the intuition to spot O(n²) disasters, pick the right data structure without thinking, and rewrite a slow function from O(n²) to O(n) in under five minutes.