Skip to content

Concept 14 // Building

Structured outputs

A structured output forces the model's answer to follow a schema fixed in advance. Its shape is constrained; its correctness still has to be measured.

  • 7 min read
  • Product manager
  • Tech lead
  • Founder
Free textSchemaUnknown

A feature reads invoices and extracts the amount. For weeks, the model returns a number. One day, it replies "The amount seems to be about 1,200 euros". A person understands. The software, which expected a number, throws an error. As soon as a program uses a model's answer, free text is no longer enough.

Three levels of control

The first level is free text: you describe the format you want in the instructions. The model follows it often, not always.

The second level is JSON mode. JSON is a data format that a program can read. As of October 2026, OpenAI's documentation states that this mode guarantees valid JSON, but not the expected fields: the answer parses without error, yet the amount can still be missing.

The third level is schema-constrained output: an answer in a format fixed in advance. The schema describes the answer's fields, their type and the allowed values. The API forces the model to conform to it. As of October 2026, according to their documentation, Anthropic, OpenAI and Google all offer this mode.

Level of control

Schema: every field is present and typed, so the right amount and a wrong one in the same format both pass the shape checks. The schema guarantees the shape, not the correctness: evals measure that.

Fig 01 // One invoice, three levels of control

Key concept

A structured output is a contract: a schema sets the answer's fields, their type and their allowed values. That contract guarantees the shape of the answer, not its correctness. Code checks the shape before anything uses it; evals (short for "evaluations") measure correctness.

Tools rest on the same idea. When a model calls a tool, for example to create a ticket or check stock, it fills in parameters described by a schema. As of October 2026, Anthropic's documentation says a strict option guarantees that these calls match the schema exactly. It also warns that when a piece of information is missing, the model may guess a value nobody gave it.

What a schema does not guarantee

A schema does not make the answer true. An amount in the right format can be the wrong amount, and a category taken from the list can be the wrong one. As of October 2026, Google's documentation in fact asks developers to plan for outputs that match the schema but are wrong in substance.

Nor does it make a confidence score reliable. If the schema asks the model to rate its confidence, you get a well-formed number, not a calibrated probability. The Other kinds of models page explains what calibration means.

Finally, the guarantee has exceptions. As of October 2026, Anthropic's and OpenAI's documentation both say so: a refusal by the model, or an answer cut off by the length limit, can fall outside the schema. So code must validate every answer, even a constrained one.

When an answer fails validation
Step 1 of 5

Code validates every answer before anything uses it, even one constrained by a schema.

Fig 02 // Validate, retry once, then fall back

Leaving room for "I don't know"

A closed list of values, for example your support team's five ticket categories, stops the model from inventing a sixth. That is the first use of a schema against hallucinations.

But a required field also forces an answer. If the invoice has no order number and the schema demands one, the model will write one anyway, even if it has to invent it. So add an "unknown" value, or allow an empty field, wherever the information can be missing. Then decide what the product does in that case: ask the user, hand over to a human, or leave the field empty.

Order number field

"Unknown" allowed: the field says unknown, and the product hands over to a human instead of sending an invented number to accounting.

Fig 03 // Leave room for "I don't know"

What it means for you

For product managers

Write the schema into the spec, not afterward: the fields, the allowed values and the planned behavior when the answer is "unknown". It is a product decision, not a technical detail. That schema then becomes the basis for the test cases, which lesson 4 of the Scoping an AI feature course covers.

For tech leads

Validate every answer in code, even with a typed output guaranteed by the API. The schema does not carry all your business rules: as of October 2026, according to its documentation, Anthropic's API does not enforce numeric bounds such as a minimum amount. On failure, retry the call once with the validation error attached. If it fails again, switch to the fallback behavior and log the incident. Version the schema like an API.

For founders

A structured output turns a demo into a feature you can plug into your CRM, your billing or your support tool. It also makes quality measurable without reviewing every answer by hand. When an enterprise customer asks how you control the AI, a schema checked on every answer is a first concrete piece of evidence.

Go deeperScoring a structured output

A free-text answer is hard to score: it takes a person, or a model as judge. A structured output is compared field by field with the expected result. A script checks that the category is right, that the amount matches and that the field really says "unknown" when the information is missing. Scoring becomes automatic and cheap. You also see which field fails. Free-text fields, such as a summary, still need another method. The Evaluations (evals) page covers these methods.

The classic mistake

fAIling RULE VII

The trap: Hallucinations are just creative suggestions

A schema makes an invention look like data. An invented order number, in the right format, passes every shape check and travels all the way to accounting. A valid format is not a correct answer: check the values, and give the model the right to answer "unknown".

Read rule VII in the manifesto

Try it

Take twenty real messages your team has received: customer requests, invoices or tickets. Pick three pieces of information to extract, with their allowed values and an "unknown" value. Fill in the table by hand. Before giving these messages to an AI assistant, remove names, email and postal addresses and account numbers, or use a tool your company has approved for this data. Then ask it to fill in the same table, and compare field by field. Above all, count the cells where you put "unknown" and the assistant gave a value.

Around this topic

Go deeperSchema limits, as of October 2026

None of the three vendors enforces the full JSON Schema standard. At Anthropic, numeric bounds and text lengths are not enforced. At OpenAI, every field must be required, so an optional piece of information has to accept an empty value. Google asks you to check in your application the constraints Gemini does not enforce. Keep schemas simple, and put business rules in your code.

Go deeperValidating is already a guardrail

Checking an output before using it is a first guardrail: the format, but also the values, such as a capped amount or a customer who exists in your database. A structured output makes these checks easy to write. It does not tell you which ones to write: that depends on the cost of an error.

What to do with it

  1. As soon as a program uses the answer, constrain it with a schema: its fields, their type and their allowed values.

  2. Validate every answer in code; on failure, retry once with the error attached, then fall back and log the incident.

  3. Allow an "unknown" value wherever information can be missing, otherwise a required field pushes the model to invent one.

Pixel portrait of François

Human mode

Want me to look at this with you?

I can work with you on the schema your AI feature's answers must follow, and the test cases that check whether they are right.

Book a call