Structured Output
Make the robot answer in a shape your code accepts.
▶ the lesson · narrated sketch video · tap for sound
the intro
Free text is hard to program against. Structured output makes the model answer in JSON that matches a schema you define, so your code can parse and use it reliably. Combine the schema with validation and a retry, and AI features become dependable.
fun fact ✦
Structured output turned “AI features” into “normal features with an AI step”.
the docs
the deep dive
the ideas behind the video — concepts, diagrams, a walkthrough and the traps to avoid
Your code cannot improvise, but the model improvises every single word. Structured output is the treaty between the two: the model agrees to answer inside a shape you define, and your code agrees to parse it. With validation and a retry behind it, an AI feature stops being a demo and starts being software.
a treaty between prose and code
key terms
JSON schema
A machine-readable description of the shape you will accept: fields, types, required.
{type: "object", required: [...]}JSON mode
An API flag that forces syntactically valid JSON. Pair it with a schema to get the right shape, not just any shape.
response_format: {type: "json"}function calling
The model returns tool names plus arguments instead of prose. Your code does the acting.
get_weather({city: "Osaka"})enum
Constrains a field to your exact options, so nothing else is possible. Perfect for routing and classification.
enum: ["yes", "no", "maybe"]how it works
- 1Define the schema
Write the exact shape: fields, types, enums, required. Keep it as flat as the task allows.
- 2Ask with the schema
Turn on JSON mode or pass the schema, so the model aims at your shape from token one.
- 3Validate the answer
Check it against the schema in your own code. Never trust, always check.
- 4Retry with the error
On failure, resend with the validation error attached. The model fixes itself remarkably well on the second try.
the code, explained
the reliability loop
side by side
JSON mode
- forces a valid JSON answer
- schema defines the fields
- model fills, code consumes
- no actions are executed
function calling
- model picks a tool by name
- returns typed arguments
- your code runs the action
- the engine of agent loops
A schema guarantees shape, not truth. A sentiment field can be perfectly valid JSON and completely wrong. Enums narrow the blast radius, evals catch the rest — parse success is not correctness.
quick answers
What if the model returns broken JSON anyway?
Retry with the parser error attached — models fix their own JSON remarkably well on the second try. Two retries cover almost everything.
Nested schemas — how deep is too deep?
Keep nesting shallow. Every level multiplies the ways validation can fail; flat objects with enums and required fields are the dependable zone.
JSON mode or function calling first?
JSON mode for answers, function calling for actions. Most features need an answer first, so start there.
quick hits about Structured Output
short answers · interviews, tips, trivia & hidden gems