Structured Output and JSON
Level 4 · Prompts inside an app
How structured output makes a model's reply fit a JSON schema. How it differs from JSON mode, and why a reply that fits can still be wrong.
Course contentsLesson 10 of 16
Level 1 · What a prompt is
Level 2 · Writing a better prompt
Level 3 · Harder and bigger tasks
Level 4 · Prompts inside an app
After this lesson you can
- Write a small JSON schema for a reply
- Tell structured output from JSON mode
- Check the values, not just the shape
12 mincovers 4 glossary entries
Worth reading first: Context Engineering
How to make a model reply in a fixed shape
Structured output makes a model's reply follow a fixed shape. Most often that is JSON that fits a schema you give it. When OpenAI added it to its API in August 2024, its newest model scored 100% on its own test of hard schemas. An older model without it scored under 40%.
JSON is a plain text format that programs read easily. It holds named fields, such as a shop name and a total. A JSON schema lists the fields you want, the type of each one and which ones must be there. The schema is the promise your code relies on.
Without a set shape, a model may add a chatty line before the data, rename a field or leave one out. Each of those breaks the code that reads the reply. With structured output on, the service only lets the model write replies that fit the schema.
JSON mode is the older and looser setting. It promises the reply will be valid JSON, so it will open in a program. It does not promise the shape. One reply may call a field city and the next one town. Use a schema whenever the shape matters.
Valid is not the same as right. A reply can fit the schema and still hold a wrong date or a made-up total. Check the values too. Is the date real? Does the total match the lines? Is that email address in the text at all?
Keep the schema small. Name fields plainly, so the name itself tells the model what goes there. Mark a field as optional when the text might not have it. A field that must be filled, with nothing to fill it, invites the model to make something up.
A schema works best with a short instruction beside it. Say what each field is for, and what to do when a fact is missing, such as leave it empty. The schema fixes the shape. The prompt still has to explain the meaning.
{
"type": "object",
"properties": {
"shop": { "type": "string" },
"date": { "type": "string" },
"total": { "type": "number" }
},
"required": ["shop", "date", "total"]
}Worked example
Jack reads receipts
Jack's app reads photos of receipts. With JSON mode, 3 of his 50 test replies call the total amount instead, and his code skips them.
With a schema, all 50 replies have the same three fields. He still checks that each total matches the lines on the receipt, and that catches 2 more.
The words for this lesson4
Check yourself
What does structured output from an AI model promise?
Finished this lesson?
Marking it complete also marks its 4 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.