# Structured Output and JSON

> 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:** [Prompt Engineering](https://learn.benibix.com/learn/ai-working-with-ai)  
**Time:** 12 min

**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

## 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.

```json
{
  "type": "object",
  "properties": {
    "shop": { "type": "string" },
    "date": { "type": "string" },
    "total": { "type": "number" }
  },
  "required": ["shop", "date", "total"]
}
```
A schema for a receipt. It has three named fields, the type of each, and all three must be in every reply.

![Two replies to the same request. A free text reply goes to a person to read. A reply in a set shape, with the fields shop, date and total, goes straight into a program.](https://learn.benibix.com/diagrams/pr-structured-output.svg)

### 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.

**Words in this lesson:** [Structured Output (LLM)](https://learn.benibix.com/term/ai/structured-output), [JSON Mode](https://learn.benibix.com/term/ai/json-mode), [JavaScript Object Notation (JSON)](https://learn.benibix.com/term/development/json), [JSON Schema](https://learn.benibix.com/term/development/json-schema)

> **The one thing to remember.** JSON mode promises the reply will open as JSON. Structured output promises it will fit your schema. Neither promises the values are true.

**Question:** What does structured output from an AI model promise?

**Answer:** That the reply fits the schema you gave. The shape is guaranteed: the fields, their types and the required ones. The facts inside those fields still need checking.

---

Source: https://learn.benibix.com/learn/ai-working-with-ai/structured-output-and-json
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-20
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
