Structured Output Reliability: Make AI Responses Survive Production

Your model returned valid JSON. Production still broke.

The currency was wrong, the date was in the past, and a field named confidence contained a beautifully formatted lie. Structured output reliability begins where syntax validation ends.

Design the Smallest Useful Contract

Every unnecessary field creates another way to fail. Start with the exact data the next component needs. Use enums for closed choices, bounds for numbers, formats for identifiers, and additionalProperties: false when surprise fields are unsafe.

Descriptions should define meaning, units, and null behavior. amount is ambiguous. amount_minor_units with a three-letter currency enum is harder to misuse. Distinguish unknown, not applicable, and empty instead of collapsing all three into null.

Version the contract. A renamed field or changed default can break saved prompts, evaluation traces, and downstream consumers even when the new schema looks cleaner.

Separate Syntax From Semantics

A schema can prove that 2026-02-30 is a string shaped like a date unless the validator checks calendar validity. It cannot know that a refund exceeds the original payment or that a cited URL does not support the claim.

Run deterministic business validation after schema validation. Check referential integrity, time windows, currency consistency, authorization scope, mutually exclusive fields, and relationships across values.

const parsed = RefundProposalSchema.parse(output);
if (parsed.amount_minor_units > payment.refundable_balance) {
  throw new DomainError("amount exceeds refundable balance");
}

Keep model confidence separate from policy. A score produced by the same model is a feature, not permission to execute.

Repair With Bounded Feedback

When output fails, return compact machine-readable errors to a repair step: field path, violated rule, and allowed range. Do not paste an enormous validator stack trace into the prompt.

Limit repair attempts. A model that fails the same invariant twice is unlikely to become trustworthy on attempt seven. Route to a deterministic fallback, request missing input, or stop safely.

Never repair silently after side effects begin. Validate the complete proposal before execution, then bind approval to a canonical payload hash so a later repair cannot change what the user authorized.

Evaluate the Ugly Inputs

Golden prompts hide reliability problems. Test missing context, conflicting instructions, giant documents, Unicode, locale-specific numbers, prompt injection, empty arrays, provider refusals, truncated output, and values just beyond every boundary.

Track first-pass validity, semantic validity, repair success, retry count, latency, and downstream task success. Segment by schema version and model version. A 99% JSON-valid rate can coexist with a disastrous 85% business-valid rate.

Store failing examples after redaction and replay them during releases. Provider upgrades and prompt edits can move errors between fields without improving the total system.

Build a Safe Failure Path

Structured generation is probabilistic input to deterministic software. Treat it like data arriving from an unreliable external client.

Timeouts need an explicit state. Partial arrays should not masquerade as complete. Unknown enum values should fail closed where actions are risky. Human review should display the original evidence, structured proposal, and validation warnings together.

The production standard is not “the model usually emits JSON.” It is that every output is validated, every correction is bounded, every side effect uses a checked payload, and every failure becomes observable instead of mysterious.