LLM Application Engineering·Intermediate·14 min

Structured Output Contract Lab

The model returned valid-looking JSON. Production still broke because syntax was never the real contract.

Experience

Work the problem before reading the explanation.

CONTRACT FAILURE

Valid JSON is not a valid business object.

You own the boundary between an LLM extractor and an order workflow.

An extraction endpoint parses successfully, but an empty items array violates a downstream invariant. Three blind retries increase latency without making the consumer safer.

Objective

Design a contract that rejects malformed and semantically invalid output before it crosses the application boundary.

Stakes

Weak contracts turn probabilistic output into deterministic downstream failures.

In one sentence

Structured output becomes reliable only when shape, semantics, repair behavior, and partial-state rules form one machine-verifiable boundary.

Loading Mission Engine…

Reflection

Turn the outcome into a rule you can reuse.

MENTAL MODEL

A contract is more than output shape.

Parseability is evidence of syntax, not evidence of semantic validity.

Reliable structured output combines an explicit schema, domain validation, bounded repair, and clear streaming semantics. The model proposes data; the application owns the contract.

—Version contracts instead of silently drifting them.
—Validate domain invariants after structural validation.
—Bound repair loops so failure cannot amplify indefinitely.

Key takeaways

Shape ≠ semantics

JSON Schema cannot express every business invariant.

Repair is policy

Retries need validation evidence and a stopping rule.

Streaming is state

Partial output needs explicit consumer semantics.

Learn More

Connect the experience to concepts, references, and transfer.

LEARNING CONTEXT

Learning context

Parseability is evidence of syntax, not evidence of semantic validity.

Not seen

CONCEPTS PRACTICED

concept-structured-output-contractStructured output as an application contract
concept-streaming-backpressureStreaming and backpressure
concept-model-vs-runtime-factModel claim vs runtime fact

Suggested backfill

No shipped prerequisite is required before entering this incident.

Transfer the model

A downstream workflow adds a new required invariant. Which part of the contract must change without breaking older consumers?

View full learning path

Carry the idea into another problem or build.

Next: capability boundaries

Apply the same contract thinking to tools and MCP capabilities.

Open MCP Mission