Structured Output Is an Untrusted Contract
Valid JSON is not a valid business decision. Parse the bytes, validate the shape, verify the meaning, then permit the action. Distinguish JSON syntax, schema validity, semantic validity, and authorization. Design narrow schemas that make invalid states difficult to express. Parse Claude output without unsafe cleanup or optimistic coercion. Repair invalid responses with bounded, evidence-rich retries. Evolve output contracts without silently breaking consumers. Test structured output at adversarial and streaming boundaries. Your support application requests a priority from 1 to 5. The response is: The JSON parser succeeds. The object has every expected key. The application routes it as the highest emergency priority, skips human review, and pages an on-call engineer. The model did not violate JSON. Your application failed to enforce the contract. Structured output has four gates: Syntax: Is there exactly one parseable JSON value? Shape: Does the value match types, required fields, enums, bounds, and additional-property rules? Semantics: Do the fields agree with domain facts and each other? Authority: Is the requested downstream action permitted? Passing an earlier gate never implies passing a later one. "Return JSON only" is an instruction. It improves probability. It does not make invalid output impossible, protect against schema drift, or validate the business meaning. When the current model and API support structured outputs, you can provide a JSON Schema and ask…
Structured Output Is an Untrusted Contract: Valid JSON is not a valid business decision. Parse the bytes, validate the shape, verify the meaning, then permit…
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.