Back to AI/ML Overview
🧩 Knowledge Site · Typed Contracts for Agentic Software · Shape, Validation, Repair

Structured Output EngineeringParseable is not valid. Valid is not correct.

A model writes text. The next program needs data it can trust. means data that follows an agreed shape, and a JSON object that parses is not necessarily valid or correct. This site starts from one field and one record and climbs, one idea at a time, to schemas, typed models, provider output modes, validation stages, bounded repair, schema evolution, security and tests, asking one question at each step: what has this check proved, and what has it not?

🎯The problem

A recommendation arrives as JSON. It parses, every field has the right type, and it still cites a rule the agent never retrieved and names the wrong policy version. Each boundary in an agent, from the intake form to the to the final answer, needs a contract, and each check on that contract proves one thing and not the next.

🔑The question every page asks
What has this check proved, and what has it not? Syntax, schema, semantics and business rules are four separate checks, shown on one synthetic underwriting recommendation.

🗺️What is inside

Contracts and four layers of checks

Why fields beat free text; syntax against schema against meaning against business validity; JSON, JSON Schema, enums, nullable fields and unions.

Typed models and provider modes

Pydantic and Java records on the same payload, the providers’ structured-output modes and constrained decoding, and tool arguments as contracts.

Validation, repair and evolution

Where each check runs, bounded repair and clarification, and adding a required field without breaking the clients that exist today.

Security, tracing and tests

Injection inside string fields, validation failures as signals, and property-based, fuzz and golden tests for every contract.

🖱️How to read it

  • New to typed output: read in order. Each chapter starts in plain English with one tiny example.
  • Experienced: jump to validation, repair, schema evolution or the insurance lab. The rigorous part sits in folded blocks.
  • Fifteen interactive labs, each with a plain table next to it. Every diagram is clickable.
  • The example is synthetic and its agent is a scripted stand-in. Results show how the mechanism works, not how good any model is.