All chapters
  1. Start hereParseable is not valid. Valid is not correct
  2. Foundations · 1From free text to fields and records: why contracts matter
  3. Foundations · 2Syntax, schema, semantics, business validity: four different kinds of right
  4. Foundations · 3JSON and JSON Schema: types, enums, nullable fields, unions and nested objects
  5. Building · 4Typed models: Pydantic in Python, records and Bean Validation in Java
  6. Building · 5Provider output modes: prompting, JSON mode, constrained decoding and tool arguments
  7. Building · 6Tool input, tool result, agent handoff, final response: four contracts on one path
  8. Building · 7Schema design: names, required or optional, and where each value came from
  9. Operating · 8Validation stages: parse, schema, cross-field, domain rules
  10. Operating · 9Errors and repair: retry, clarify, correct within bounds, fall back
  11. Operating · 10Schema evolution: versions, compatibility and migrations
  12. Operating · 11Security: a valid string can still be an attack
  13. Operating · 12Observing contracts: validation failures, schema drift and replay artifacts
  14. Operating · 13Testing contracts: golden examples, property-based tests, fuzzing and contract suites
  15. Reference · 14Frameworks and standards: what each one checks for you
  16. Reference · 15Advanced: partial objects in a stream, polymorphism, multilingual data and typed events
  17. Reference · 16The insurance lab: one submission, four contracts, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources

Structured Output Engineering · typed contracts at every agent boundary

A model writes text. The next program needs data it can depend on. A JSON object that parses is not necessarily valid, and a valid one is not necessarily correct. This site starts from one field and one record and climbs, one idea at a time, to the checks, repairs and versions that let a program trust what a model wrote, and it asks the same question at every step: what has this check proved, and what has it not?

For engineers and architects who connect language models to other programs. One running example, and code that runs without a model, a network or an API key.

Two sentences
Parseable is not valid. Valid is not correct. What each one means, shown on one answer.
A typed contract
A form with boxes instead of a letter: an agreed shape plus the rules both sides rely on.
The example
One broker email, one recommendation, and one underwriter who decides. Every page uses it.
Where this fits
Which sister site owns the neighbouring questions, and how to read this one.

A broker has asked an insurer for a quote on a masonry office. The request is submission SUB-1004, and the series calls it case UW-004. The application says the roof was replaced 9 years ago. An outside roof-data provider says the roof is 22 years old. The insurer's rules, an illustrative set this site calls the policy fixture, have a rule for that: R-ROOF-03 says that when the two ages differ by more than 5 years, a senior underwriter must settle it.

The underwriting agent, a program that uses a language model, reads the case and answers. Its first answer is this:

I recommend that this submission is escalated to a senior underwriter. The application says the roof is 9 years old, but the roof-data provider reports 22 years, a gap of 13 years, which is more than rule R-ROOF-03 allows. I am fairly confident in this (about 60%). A person should make the final decision under policy 2026.2.

A person reads that and nods. It is right. But the next reader is not a person. It is the underwriter cockpit, the web application that puts the case in front of the right underwriter. The cockpit must put the case in the senior underwriters' queue, link the cited rule, sort the queue and store the result. To do any of that it has to find the word "escalated" in a paragraph, guess that it means the same as "escalate", and hope the next answer uses the same word.

So the team asks the model for JSON. The next answer parses without an error:

{"recommendation": "approved", "reasons": ["The application says the roof is 9 years old; the roof-data provider says 22 years.", "The two ages differ by 13 years, more than the 5 years rule R-ROOF-03 allows, so a senior underwriter should look."], "citations": ["R-ROOF-03"], "missing": [], "stated_confidence": 0.62, "requires_human": true, "policy_version": "2026.2"}

The parser is happy, and the cockpit is not. The agreed words are approve, decline, request_info and escalate. "approved" is none of them, so there is no queue for it, and the reasons argue for escalation anyway.

On another submission, case UW-002 (a sprinklered masonry warehouse with a roof of 8 years), an answer arrives with every field in the agreed shape: decline, citing R-ROOF-01. That rule is about roofs older than 25 years in wind zone C. It does not apply to an 8-year roof. The shape is perfect, and the content is false.

Three answers, three different problems. That is what this site is about, in two sentences: Parseable is not valid. Valid is not correct. Each answer above is one of this site's own cases (UW-S01, UW-S04 and UW-S10; the cases named UW-S.. belong to this site, the UW-0.. cases to the whole series).

A form with boxes, not a letter#

Before software, an insurer had the same problem with people. A broker who writes a letter can say anything in any order. A clerk has to read every letter and find the facts. So insurers printed forms: a box for the year built, a box for the floor area, a tick box for sprinklers. The form does not make the broker honest. It makes the answer easy to find, easy to compare and easy to check.

Structured output is the same idea for a model: data that follows an agreed shape. Instead of a paragraph that mentions a recommendation, the model writes one field named recommendation that holds one of four known words. A program can read that field without guessing.

A contract is the agreement behind the form. It names the shape (which fields, which kinds of value, which words are allowed) and the rules both sides rely on (an escalate must cite a rule; requires_human is always true). The side that writes promises to keep it. The side that reads may assume it. The machine-readable description of the shape is called a schema, and Four layers shows why a schema is only part of a contract.

Before AI. A Java service that accepts an order as JSON maps it to a class and checks it (in the Java world, with Jakarta Bean Validation) before any business code runs; a relational table refuses a row whose NOT NULL column is empty. The same discipline applies here, with one difference: the producer is a model. It writes fluent text by default, can give a different answer to the same input, and will fill a box with a plausible value that nothing in its input supports.
Common confusion. "The model returned JSON" is a statement about syntax. It says nothing about whether the fields are the agreed ones, whether they agree with each other, or whether they are true.

The example in one minute#

Every page uses the same synthetic case. An insurer sells commercial property insurance through brokers. A broker's quote request arrives as an email. The intake agent reads the email once and writes a submission: one JSON record with 63 fields, of which the examples carry about ten. From then on no program reads the email again.

The underwriting agent reads the submission. It calls tools (functions that the surrounding program runs for it): it fetches a roof assessment from the roof-data provider, retrieves the insurer's guidance, and runs deterministic eligibility rules in code. Then it writes a recommendation: one of four words, the reasons, the rule ids it cites, the fields it is missing, a confidence it states about itself, and the version of the policy fixture it read. Code checks that output, wraps it in a recommendation record and stores it. An underwriter, the person at the insurer who decides whether to accept a risk, sees it in the underwriter cockpit and approves or declines. The model recommends; a person decides.

Diagram: One quote request, from email to decision · every arrow is a contract

Read left to right. The broker writes sentences. The intake agent turns them into a record. The underwriting agent gathers evidence with tools and writes a recommendation. Code checks it and stores it. A person decides, in a lane of its own. Each arrow is a place where one program hands data to another.

  1. 1 · The request
    1. Broker email: The quote request as a person writes it. Nothing in it has an agreed shape.
  2. 2 · Intake
    1. Intake agent: Reads the email once and writes the submission record.
    2. Submission: One record per quote request. Every later step reads this, never the email.
  3. 3 · Assessment
    1. Underwriting agent: Fetches the roof assessment, reads the guidance, runs the rules in code, and writes a recommendation.
    2. Recommendation: What the agent proposes, with reasons, rule ids and missing fields. A proposal, never a decision.
  4. 4 · The workflow
    1. Checks: Code checks the output before anything is stored or shown.
    2. Stored record: Code wraps the checked recommendation with identifiers the model must not invent.
  5. 5 · The decision
    1. Underwriter: Reads the recommendation in the underwriter cockpit and decides. The model recommends; a person decides.

Read the diagram for who writes and who reads. Every arrow is a place where one program hands data to another, and each of those places needs a contract. This site follows four of them: the arguments the agent passes to a tool, the result the tool returns, the handoff between agents, and the final recommendation.

In our insurance agent. This is an illustrative reconstruction for teaching. The cases, the rules, the fields, the provider and every number are invented. Nothing here reports the quality of a real system or model. The roof thresholds are synthetic, not insurance practice.

The example code lives in examples/uw-contracts/. It is standard-library Python, and the model in it is a scripted stand-in, so these results show how the mechanism works, not how good any model is. This is the run of the first answer above:

cd examples/uw-contracts
python3 run_contracts.py --case UW-S01
The model here is a scripted stand-in: these results show how the mechanism works, not how good any model is.

case     boundary     first failure  outcome                      attempts
UW-S01   final        parse          accepted_after_reask         2
   attempt 1: first failure parse, action re_ask
      [parse] (whole output) parse: unexpected character 'I' at position 0
   attempt 2: first failure -, action accept

The paragraph fails at the very first check, because it is not JSON at all. The workflow sends the error back to the model, and the second attempt passes all four checks. What those four checks are, and why there are four, is the subject of the first two chapters.

Three forms of the same answer#

The lab below holds the UW-004 recommendation in three forms: the paragraph, a loose JSON object that a model might write when nobody agreed on the keys, and the strict contract. Pick a form and see which checks it passes and what a consuming program can do with it.

The same comparison without the lab. "Guess" means a program can do it only by interpreting words that nobody agreed on.

What a program must doFree-form proseLoose JSONThe strict contract
Route to the right queueguessguessyes
Link the cited rule to the policy fixtureguessnoyes
Check the cited rule against the facts in codenonoyes
Sort the queue by stated confidencenonoyes
Prove that a person must decideguessguessyes
Store it in typed columns and query it laternoguessyes

Only the last column lets a program act without reading like a person. It still does not make the recommendation true; that takes the checks that come after the shape.

What this is not. This site does not teach how to write the instructions that ask a model for structure (prompt.sammuthu.com) or where tool schemas live and how a tool call runs (tools.sammuthu.com). It owns the data contract: shape, validation, repair, compatibility and type safety.

Where this fits#

This site is one of a series on AI-native engineering. Each site owns one question about building with agents and links to the others at the seams. The tiles follow the life of one agent run, from what the model reads to how the result is shipped and kept healthy. This site is marked.

What the model reads.

What the run does.

What checks the result.

What keeps it running.

Three seams come up on almost every page. A contract decides whether one output is acceptable; eval.sammuthu.com measures how good many outputs are. A contract checks the shape and the rules of the data; guardrails.sammuthu.com owns the wider checks around the agent. And a validation failure is recorded here as data; the logs, traces and spans that carry it belong to observe.sammuthu.com.

How to read this site#

The chapters follow the order in which the questions come up when a team connects its first model to a program. First the words and the four kinds of right. Then the tools that describe and hold a shape, and the places on the path where a contract is needed. Then what happens when a check fails, when the contract changes, and when a valid string is an attack. A reference part closes the site.

Diagram: The route through this site · four parts, each one assumes the one before

Read left to right. Foundations give the words and the four kinds of right. Building puts a shape into code, asks a model for it, and places contracts on the path. Operating covers what happens after a check fails or the contract changes. Reference holds the tools, the hard edges and the whole example.

  1. 1 · Foundations
    1. Contracts: Why a program cannot depend on a sentence, and what a contract promises.
    2. Four layers: Parses, has the shape, agrees with itself, is true here.
    3. JSON Schema: Types, enums, null versus absent, unions, closed objects.
  2. 2 · Building
    1. Typed models: The same recommendation held by Python and Java code.
    2. Provider modes: What each way of asking a model guarantees, and what none does.
    3. Four contracts: Tool input, tool result, handoff, final response.
  3. 3 · Operating
    1. Validate and repair: Stages in a fixed order, then a bounded loop that ends with a person.
    2. Evolve and secure: New versions without breaking readers; valid strings that carry instructions.
    3. Observe and test: Failures as records, drift, golden examples and fuzzing.
  4. 4 · Reference
    1. Frameworks and advanced: Standards, libraries and products read on their own documents; streaming and polymorphism.
    2. Insurance lab: One submission through every contract, with the code.

Foundations. The vocabulary, and the difference between parsing, shape and truth.

Building. Holding a shape in code, asking a model for it, and placing contracts on the path.

Operating. Checking, repairing, changing, securing, observing and testing a contract.

Reference. Tools, hard edges, and the whole example.

Each page serves three readers. The first reading is plain English, with every new word defined by one sentence and one tiny example before it is used. Callouts marked Before AI compare an idea with Java, Spring, Kafka or a relational database for a backend engineer. Blocks that open with a plus sign hold the depth for an agent developer: edge cases, trade-offs and competing designs. Skip them on a first reading; nothing later depends on them.

Why this is harder with a model than with a serviceFour properties of a model as a producer

A service written by a team is a producer you can read: its output shape is in its code, and it changes when someone merges a change. A model as a producer differs in four ways that matter for contracts. It can give a different output for the same input, so one passing example proves little about the next run. Its default output is fluent text, so the shape has to be requested and then checked. It can fail in ways a service rarely does: stop in the middle of an object when it reaches its output limit, refuse, or copy text from its input into a field. And its behaviour can change when the model version, the instructions or the retrieved context change, without any change to the contract. Each of these has a home on this site: variation and the four layers in Four layers, cut-off output in Provider modes, copied instructions in Security, quiet change in Observability.

What a typed contract cannot carryThe limits this site keeps in view

A contract can say that recommendation is one of four words and that decline must cite a rule. It cannot say that the reasons are well argued, that the agent looked at the right evidence before writing, or that escalate was the best call for this building. The first two are measured across many runs on eval.sammuthu.com; the last one is the underwriter's job. The design consequence runs through every chapter: put every rule that code can decide for certain into the contract and its checks, record what the checks could not decide, and never let a passed check read as "the answer is right".

Checklist#

In one breath#

A model writes text, and the program after it needs data it can depend on, so the two sides agree a contract: a shape plus the rules both rely on. Parsing proves only that the text is JSON; the shape proves only that the boxes are filled with the right kinds of thing; neither proves that the answer is true. This site builds the checks, repairs and versions for each of those gaps, on one insurance example where the model recommends and a person decides.

The next page starts at the bottom: what a field, a record and a type are, who writes and who reads, and what a contract promises to whom. It ends with one broker email turned into one record, and with the first sign that a record in the right shape can still hold the wrong number.