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.

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…

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.

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.

LEARNING CONTEXT

Reusable mental model

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

Next: capability boundaries

Apply the same contract thinking to tools and MCP capabilities.

Open MCP Mission