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 is | It is not |
|---|---|
| A ladder: one idea per step, each word in plain English with a tiny example before it is used | A 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-S20 | A 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 code | A 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 works | A 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 apart | A 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.
| Site | Owns |
|---|---|
| prompt.sammuthu.com | how instructions are written, composed and defended |
| context.sammuthu.com | what the model can see now: selection, retrieval, budget |
| memory.sammuthu.com | durable information and saved execution state |
| a2a.sammuthu.com | messages between agents; the A2A protocol |
| observe.sammuthu.com | logs, metrics, traces, audit events, replay |
| guardrails.sammuthu.com | enforceable checks around a probabilistic agent |
| tools.sammuthu.com | callable capabilities: tool schemas, execution, MCP tools |
| schema.sammuthu.com (this site) | typed contracts: shape, validation, repair, evolution |
| orchestrate.sammuthu.com | the control plane: what runs next, under which condition |
| reliable.sammuthu.com | acceptable outcomes despite failures, retries and load |
| harness.sammuthu.com | the runtime around a model call |
| eval.sammuthu.com | measurement: graders, golden sets, judges, release gates |
| diff-to-deploy.sammuthu.com | shipping 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.
| Part | Status |
|---|---|
| JSON, JSON Schema, JSON Pointer, Jakarta Validation | Standards, described from their own specifications (links below) |
| Pydantic, Jackson, Hibernate Validator and the other libraries | Described 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 features | Described 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 contract | Common practice in service and data engineering |
| Output encoding per sink, parameterized queries | Common practice in web security; quoted from OWASP guidance |
| The four layers (syntax, schema, semantics, business validity) and the four stages | An 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 recommendation | Designs proposed on this site |
| The insurance example and its cases | Invented 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:
- RFC 8259, The JSON Data Interchange Format: rfc-editor.org/rfc/rfc8259
- RFC 6901, JSON Pointer: rfc-editor.org/rfc/rfc6901
- JSON Schema 2020-12, core and validation: json-schema.org/draft/2020-12
- Jakarta Validation 3.1: jakarta.ee/specifications/bean-validation/3.1
- Pydantic documentation: pydantic.dev/docs
- Jackson databind features: github.com/FasterXML/jackson-databind/wiki
- Model Context Protocol, tools (revision 2026-07-28): modelcontextprotocol.io
- W3C Trace Context: w3.org/TR/trace-context
- OWASP Top 10 for LLM Applications 2025, LLM05: genai.owasp.org
- OWASP Cross Site Scripting Prevention Cheat Sheet: cheatsheetseries.owasp.org
- A Kafka schema registry's compatibility documentation: docs.confluent.io
- Hypothesis (property-based testing): hypothesis.readthedocs.io; Pact (contract testing): docs.pact.io
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.