Structured Outputs Overview
From prose to contracts
LLMs are fluent in prose and sloppy with schemas. Structured outputs — JSON under a schema — turn free text into parseable contracts, and parsing failures into design failures.
What you will learn
- Explain why structured output matters for apps
- Name the failure modes of text-to-JSON
- Decide when to enforce structure vs free text
What is this?
Structured output constrains generation to follow a schema — JSON with required fields, types, enums — via platform JSON modes or rigorous prompt+validation. This turns model calls into dependable data operations: one shape in, one shape out, parsed and validated downstream instead of regex-guessed prose.
Why do you need it?
- Your code shouldn't regex-parse model prose — it should receive typed data.
- Enforcement (guaranteed schema) beats assertion (check after) when the platform offers it.
- Invariants travel: routes, tools, and UI all consume one contract.
- Out-of-schema garbage is the #1 source of silent app breakage.
Mental model
Forms with dropdowns, not write-in fields
Structured outputs
A paper form with free-text 'date' fields invites 'tomorrow', 'Thursday-ish'. A validated date field refuses and restates the format. Structured output is that well-designed form: the model fills fields exactly, or it's rejected and redone.
How it works
- Define the schema (types, required fields, enums).
- Platform structured mode (if available) constrains decoding to the schema.
- Otherwise: prompt the schema explicitly + parse and validate strictly.
- Invalid output → retry/prompt-repair loop or honest failure.
- Consumers import the same schema for type safety (see type-safe TS).
Text to contract.
In production
- Function calling arguments are structured output under the hood.
- Extraction pipelines emit typed records directly into databases.
- UI widgets receive validated JSON for rendering, free of malformed blobs.
Best practices
- Prefer platform-enforced structured modes when available.
- Keep schemas minimal: fewer required fields, fewer surprises.
- Validate on a schema version you control, not the model's mood.
- Treat a parse failure as an engineering event with an alert.
Common mistakes
- Trusting 'please output JSON' in a prompt and regex-parsing the result.
- Required fields allowed optional by laziness.
- N+ schema versions drifting between production and evaluation.
Common issues
Parsing fails intermittentlyModel outputs prose around JSON
Enable structured mode or add strict prompt + repair loop.
Valid JSON, wrong shapeSchema not communicated clearly
Inline the schema; validate and retry on mismatch.
Debugging tips
- JSON flake reasons (extra prose, comments, backticks) → enforce schema, not prompts.
- One field sometimes missing → it should be optional or the generate prompt forces defaults.
- Type drift (number vs string) → schema enforcement or stricter validation first.
Interview checkpoint
Hands-on lab
- Declare expected keys and types for a reply
- Reject replies missing keys or carrying wrong types
- Retry parsing until a reply validates
Validate a Structured Reply
25 min · beginner
Quick quiz
The most reliable way to get schema-valid output is…
Free-text prompts are a reliable JSON generator.