Free Code lesson

Structured output: getting predictable JSON from an AI model

Structured output means asking an AI model to return data in a fixed shape, usually JSON that follows a schema you define, so your app can read it without guessing. This lesson explains why that matters, how the major model APIs support it, and how to validate results and recover when they fail, all in prose with no code listings.

For you or your whole team

Start with a useful first step.

7-day free trial. No credit card needed.

You will continue on the Tosheo.ai app to create your account and review the trial terms.

What this lesson builds

Skills worth putting to work.

Schema design

Defining required fields, types, allowed values and nulls for honest gaps.

Using API enforcement

Choosing schema-constrained output over prompt-only JSON where the API supports it.

Two-layer validation

Checking the shape with a schema library and the values with business rules.

Failure handling

Handling refusals, truncated replies and failed checks with capped retries and human fallback.

Example task / fictional source material

Design the Parcelwise extraction

In prose, design the structured output for the fictional Parcelwise email tool: list each field with its type, whether it is required and a one-line description, then write the business rules you would validate and your retry and fallback rule. Ask an AI tool to find three fictional emails that would break your design, and revise it.

Review criterion

Complete schema

Every field has a type, a required flag and a clear description, with null allowed for honest gaps.

Review criterion

Business rules

At least three value checks go beyond the schema, such as date and reference checks.

Review criterion

Failure plan

Refusals, truncated replies and failed checks each have a defined response.

Review criterion

Stress tested

The design is revised after testing against awkward example emails.

Copy and adapt

Prompts to try

Replace the parts in square brackets with your own details, and check every output before you use it.

Schema review

Here is a field list for extracting data from [document type]: [field list with types]. Point out ambiguous field names, missing null options, values that should be restricted to a fixed list, and descriptions that need tightening.

Edge case generator

Write six short, fictional [document type] examples that would be hard to extract into these fields: [field list]. Include conditional requests, missing values and conflicting details. After the examples, explain what makes each one hard.

Business rule checklist

For an app that extracts [fields] from [document type], suggest validation rules beyond the schema that check whether values make sense, and say what the app should do when each rule fails.

Why do AI apps need structured output?

AI apps need structured output because software cannot read a friendly paragraph reliably; it needs the same fields, with the same names and types, every time. One extra sentence or a missing field can break the next step of your app.

Picture a fictional 12-person logistics start-up, Parcelwise. Its developer, Sana, is building a tool that reads customer emails and fills a delivery change form: order reference, requested date, new address, and whether the customer is asking for a refund. A typical email reads: 'Hi, order PW-88213, I won't be in on Thurs, can you bring it Sat instead? Or leave with no. 14. If not just cancel and refund pls.' Her first version asks the model to 'reply in JSON'. Most replies parse, but some begin with 'Sure, here is the JSON', some name the field 'date' instead of 'requested_date', and one returns the date as 'Saturday'.

What is a JSON schema and why does it help?

A JSON schema is a formal description of the data you expect: which fields exist, which are required, what type each one is and which values are allowed. Giving the model a schema turns 'please reply in JSON' into a contract your code can check.

For Sana, the schema says: order_reference is a required string; requested_date is a required string in date format, or null if no date was given; new_address is a string or null; refund_requested is a required boolean; and no other fields are allowed. That last rule stops the model adding commentary fields.

How do model APIs support structured output?

Major model APIs let you pass a JSON schema with the request, and the model's output is constrained to match it.

OpenAI

OpenAI's Structured Outputs feature constrains responses to a supplied JSON schema when strict mode is on. Its documentation distinguishes this from the older JSON mode, which only ensures valid JSON, not adherence to your schema, and recommends Structured Outputs where available.

Anthropic

Claude's API offers JSON outputs that match a schema you provide, plus a strict option on tool definitions so tool inputs are validated against the tool's schema. Its documentation lists which schema features are supported and which return an error.

Google

The Gemini API accepts a JSON schema for responses and supports a defined subset of schema keywords. Its documentation says that while output is syntactically correct JSON, you should still validate the values in your application.

Why do you still need validation and retries?

You still need validation because a schema controls the shape of the data, not whether the values are right. A perfectly formed reply can still carry the wrong date, an invented order reference or a refund flag the customer never asked for.

Validate in two layers. First, check the shape with a schema library, such as Pydantic in Python or Zod in JavaScript, which the OpenAI, Anthropic and Google documentation all show in examples. Second, check business rules: does the order reference match the pattern and exist in the system, is the date in the future and a delivery day, and is the address in a delivery area? Also handle the cases the providers document: a refusal, which may not follow your schema, and a reply cut off by the maximum token limit, which leaves incomplete JSON.

Retry carefully. If a check fails, send one retry that includes the specific error, such as 'requested_date must be a date; the email says Saturday, and the order date is 14 October'. Cap retries at one or two, then route the email to a person.

What does weak and robust structured output look like?

Weak version: the prompt says 'Extract the details and reply in JSON.' The app reads whatever comes back. For the email above it receives fields called order and date, a date value of 'Saturday', and a refund value of true, because the model treated 'if not just cancel' as a firm request. The form fills wrongly and the customer gets a refund they did not want.

Robust version: the request includes Sana's schema with strict mode, and the prompt explains each field, including 'refund_requested is true only if the customer asks for a refund unconditionally'. The model returns order_reference PW-88213, requested_date as the next Saturday's date, new_address null, refund_requested false and conditional_request, a field Sana added to the schema for exactly this case, set to 'refund if Saturday or neighbour is not possible'. Validation confirms the order exists and Saturday is a delivery day. Because the email contains a conditional request, the rules send it to a person for the final call.

What are the common structured output mistakes?

The most common mistake is trusting valid JSON as correct data. Others: relying on prompt instructions alone when the API offers schema enforcement, using vague field names without descriptions, forcing a value when the honest answer is null, ignoring refusals and truncated replies, and retrying without telling the model what was wrong.

Where does structured output fit in the Tosheo.ai catalogue?

Structured output is a Code lesson in the build AI apps course, in the Building AI Apps category. The full hands-on version with code, where you define a schema, call an API, validate replies and add a retry, is in the Code track after sign-up, with rubric feedback on each step.

Sources and scope

OpenAI API documentation, Structured Outputs guide, JSON mode comparison and refusals (checked 19 October 2026) ↗

Anthropic Claude documentation, structured outputs and strict tool use (checked 19 October 2026) ↗

Google Gemini API documentation, structured output and validation advice (checked 19 October 2026) ↗

Before you decide

A few good questions.

What is structured output in AI?

Structured output is when an AI model returns data in a fixed format, usually JSON that follows a schema you define, so an app can read the fields reliably instead of parsing free text.

What is the difference between JSON mode and structured outputs?

In OpenAI's documentation, JSON mode only ensures the reply is valid JSON. Structured Outputs also makes the reply follow your supplied schema, with the right fields and types.

If the model follows my schema, do I still need validation?

Yes. A schema controls the shape, not the truth. Check values against business rules, such as whether a reference exists or a date is valid, and handle refusals and truncated replies.

How many times should an app retry a failed extraction?

Usually once or twice, with the specific error included in the retry. After that, send the item to a person, because repeated failures often mean the input itself is ambiguous.

Do I need to know how to code for this lesson?

No. This page explains the ideas in prose. The hands-on version, where you write the schema, call an API and add validation, is in the Code track of the build AI apps course after sign-up.

Give your team a path, not another playlist.

Explore role-specific lessons, practical tasks and the manager view.

Start free trial7-day free trial · No credit card needed

Structured output: getting predictable JSON from an AI model

Start with a useful first step.

Skills worth putting to work.

Schema design

Using API enforcement

Two-layer validation

Failure handling

Design the Parcelwise extraction

Complete schema

Business rules

Failure plan

Stress tested

Prompts to try

Schema review

Edge case generator

Business rule checklist

Why do AI apps need structured output?

What is a JSON schema and why does it help?

How do model APIs support structured output?

OpenAI

Anthropic

Google

Why do you still need validation and retries?

What does weak and robust structured output look like?

What are the common structured output mistakes?

Where does structured output fit in the Tosheo.ai catalogue?

Sources and scope

A few good questions.

Keep exploring.

Build AI apps course with a hands-on Code track

Lesson: retrieval-augmented generation explained

AI agents development course

Python course for professionals

All free AI lessons

Give your team a path, not another playlist.