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

prompt+schemamodelJSON outvalidator
the answer passes through your schema before your app trusts it

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

  1. 1
    Define the schema

    Write the exact shape: fields, types, enums, required. Keep it as flat as the task allows.

  2. 2
    Ask with the schema

    Turn on JSON mode or pass the schema, so the model aims at your shape from token one.

  3. 3
    Validate the answer

    Check it against the schema in your own code. Never trust, always check.

  4. 4
    Retry 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

1let out = await ask(input, Schema)
2for (let i = 0; i < 2; i++) {
two retries catch almost everything
3 const err = validate(out, Schema)
shape and content checked in your code
4 if (!err) break
5 out = await ask(input, Schema, err)
the error goes back in — the model self-corrects
6}
7return out

side by side

JSON mode

  • forces a valid JSON answer
  • schema defines the fields
  • model fills, code consumes
  • no actions are executed
VS

function calling

  • model picks a tool by name
  • returns typed arguments
  • your code runs the action
  • the engine of agent loops
🪤 gotcha

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

🎤 interview

JSON mode or function calling?watch ↗

📚 tutorial

Why does free text break apps?watch ↗

🔧 useful

The reliability loopwatch ↗

💎 deep

Need one of exactly three answers?watch ↗

💎 deep

Schema + retry = dependablewatch ↗