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
About

About this site and its sources

What this site is, what it is not, the sister sites, where its ideas come from, and how the facts were checked.

This is a teaching site about structured output for agentic software: how to turn flexible model text and tool data into typed contracts at every boundary of an agent system, and how to check, repair, evolve, secure, observe and test those contracts. It starts from one field and one record and climbs to provider output modes, validation stages, bounded repair and schema evolution, asking at each step what a check has proved and what it has not. It is written for engineers who build or operate agent systems: a newcomer to AI-native building, an experienced backend engineer, and an advanced agent developer.

One example runs through every page. An insurer receives a broker's request for a quote. An intake agent turns the email into a submission, an underwriting agent reads it, calls tools and writes a recommendation, and a human underwriter decides. The model recommends; a person decides.

What it is and is not#

It isIt is not
A ladder: one idea per step, each word in plain English with a tiny example before it is usedA standard, or the only way to design contracts
One running example: the shared series cases UW-001 to UW-010 and this site's own cases UW-S01 to UW-S20A record of any real insurer. The cases, rules, fields, names, addresses and the provider are invented; the roof thresholds are synthetic
Code that was run: a small standard-library Python example with its real output, and a recorded run of real Pydantic and Java codeA library to install. The validator implements only the part of JSON Schema the site teaches
A demonstration of method: the model is a scripted stand-in, so every result shows how a mechanism worksA measurement of any model or product. No page reports how good a real system is
Standards, libraries and products described from their own documentation, read on the date given, kept apartA ranking or a buying guide. No tool is called best, and no price is quoted

Sister sites#

This site is one of the AI-native Engineering guides. Each owns one subject; at a seam, a page says in one sentence what the neighbouring concept is and links the site that owns it.

SiteOwns
prompt.sammuthu.comhow instructions are written, composed and defended
context.sammuthu.comwhat the model can see now: selection, retrieval, budget
memory.sammuthu.comdurable information and saved execution state
a2a.sammuthu.commessages between agents; the A2A protocol
observe.sammuthu.comlogs, metrics, traces, audit events, replay
guardrails.sammuthu.comenforceable checks around a probabilistic agent
tools.sammuthu.comcallable capabilities: tool schemas, execution, MCP tools
schema.sammuthu.com (this site)typed contracts: shape, validation, repair, evolution
orchestrate.sammuthu.comthe control plane: what runs next, under which condition
reliable.sammuthu.comacceptable outcomes despite failures, retries and load
harness.sammuthu.comthe runtime around a model call
eval.sammuthu.commeasurement: graders, golden sets, judges, release gates
diff-to-deploy.sammuthu.comshipping a change with coding agents: hooks, review, CI

What is original here and what is not#

Most ideas on this site are older than language models: typed contracts, validation, tolerant readers, compatibility directions, output encoding and contract testing come from decades of service, database and web engineering. This site applies them to a producer that is a model.

PartStatus
JSON, JSON Schema, JSON Pointer, Jakarta ValidationStandards, described from their own specifications (links below)
Pydantic, Jackson, Hibernate Validator and the other librariesDescribed from their own documentation; the Pydantic and Java behaviour shown is from one recorded run with the versions named on the typed-models page
Provider structured-output featuresDescribed from each provider's documentation, read on the date in the fact log; vendor documentation changes often
Backward and forward compatibility, tolerant reader, expand and contractCommon practice in service and data engineering
Output encoding per sink, parameterized queriesCommon practice in web security; quoted from OWASP guidance
The four layers (syntax, schema, semantics, business validity) and the four stagesAn arrangement proposed on this site
"The model fills what only it can know; code stamps the rest", provenance per field, the fallback record with no recommendationDesigns proposed on this site
The insurance example and its casesInvented for this series

Sources#

Each chapter keeps a fact log in the repository (docs/facts/<page>.md): every claim about a standard, library or product, with its URL and the date it was read. The primary sources include:

The provider pages and the framework profiles each cite their own documentation in place.

How the facts were checked#

A claim about a product, protocol or standard was written only after reading its own documentation on the day given, and logged with the URL. Where a page did not say something, the text says "the documentation read here does not say". A surprising claim (a deprecation, a rename, a moved page) was read a second time before publication. Every Python command shown on a page was run in a copy of the example, and its output was pasted, not typed. The labs run the same functions as the Python code, ported to JavaScript and checked against the Python results row by row.

The code#

The example lives in the site's repository under examples/uw-contracts/: standard-library Python 3, no key, no network, 43 unit tests, a README that maps every concept to a function. The labs read data generated from it. The Pydantic and Java comparison under examples/uw-contracts/twins/ was run once, outside the repository, with the exact versions in its README.

The author is Sam Muthu.