The problem
A team prompts a model in free-form prose to "return a JSON object with fields: name, amount, and date." Most of the time, it works as intended. Occasionally, the model wraps the JSON in an explanatory markdown paragraph, uses single quotes instead of double quotes, or omits an optional field. The parser crashes silently in production once every few hundred calls — rare enough to slip through smoke testing, yet frequent enough to cause severe production incidents at enterprise scale.
The root cause is not that the model "inexplicably failed." It is treating a natural language instruction ("respond in JSON") as a structural guarantee. Prompt-level instructions are strong suggestions, not deterministic contracts.
Enforce schemas via tool use and tool_choice, not loose instructions
The robust method for guaranteeing output structure is not asking politely in the prompt — it is providing an explicit JSON schema via tool definitions and leveraging tool_choice to constrain the model to that schema. Even when the "tool" does not trigger an external side effect (serving purely as a structured data extraction schema), this technique applies: you define the exact parameter properties, types, and required fields, and force the model to invoke it.
This dramatically mitigates structural defects (malformed JSON, missing keys, invalid types) because generation is constrained directly by the schema definition rather than guided purely by token probability. However, mitigating structural errors does not eliminate semantic errors: a schema guarantees that amount is a number, not that the number matches ground truth.
Validate, retry, and return semantic errors
When an output fails validation — whether structural or semantic — the naive reaction is discarding the output and re-issuing the identical prompt, hoping for better luck on a second attempt. This blind retry pattern burns latency and cost while yielding low conversion, because the model receives zero new information about why its previous attempt was rejected.
The defensive architecture closes the feedback loop: when validation fails, the specific error — not a generic "try again", but an actionable message like "field date must conform to ISO-8601" or "total amount does not match the sum of itemized costs" — is returned directly to the model in the next turn. This converts a blind retry into targeted error recovery with significantly higher recovery rates.
Two independent failures, two independent defenses
This connects directly to output evaluation: structural failure (schema violation) and semantic content failure (factual hallucination within a valid schema) are orthogonal defects requiring distinct architectural defenses:
- Defenses against structural failure: JSON Schema definitions via tool use +
tool_choice, automated schema validation, and retry loops returning schema parse errors. - Defenses against content failure: Semantic validation comparing extracted facts against source grounding or domain heuristics (does the amount match the source invoice? is the date within a permissible window?), completely independent of format parsing.
A resilient system decouples both layers. An output can easily satisfy structural validation while failing semantic assertions — a pipeline that only checks syntax is completely unprotected against semantic failure modes.
Where intuition fails
- "If I clearly instruct the model to respond in valid JSON, it will always comply." Natural language instructions provide no structural guarantees — occasional formatting anomalies are mathematically inevitable without schema enforcement.
- "If validation fails, simply retrying the same prompt is sufficient." Without returning the explicit failure reason, blind retries exhibit low success rates; the performance gain comes from closing the loop with actionable error signals.
- "A strict JSON schema guarantees data accuracy." A schema guarantees syntax, not truth. Semantic validation against source documents remains mandatory.
Put it into practice
In this lesson's lab, you will implement an extraction pipeline featuring two-stage validation — structural schema checking followed by semantic content verification — paired with an error-recovery feedback loop that feeds validation failures back into the model to measure recovery rates against blind retries.