When schema validation fails, what should the repair turn send back to the model?

## The repair loop in one sentence Validate the model's structured output; if it fails, send the validator's own error back as a new turn and ask for a corrected object; validate again; cap the attempts. The loop is simple. Almost all of the engineering quality lives in what goes into that second message. ## Give the model a compiler error, not a build failure The single biggest determinant of repair success is error specificity. Compare two repair turns after a customs declaration fails validation: - `"Your output was invalid. Please try again following the schema."` - `"Validation failed: commodity[2].hs_code: expected 6 digits, got \"8471.30.01\". Return the corrected object only." The first tells the model nothing it did not already believe — it thought the output was fine. It will typically resample something close to the original and fail identically, having cost a full generation. The second names the location, the constraint and the actual value, which is enough to make the correction mechanical: strip the separators, keep six digits. So the repair message should carry, at minimum: the **path** to the failing field in a form that matches the document's structure, the **constraint** that was violated stated in plain terms, the **actual value** verbatim, and an explicit instruction about the expected response format. If several fields failed, list them all — models fix them in one pass, and one turn is cheaper than three. ## Send the offending output, but not necessarily all of it The model needs to see what it produced to correct it. For small documents, include the whole prior output. For large ones — a declaration with fifty commodity lines — sending the whole thing back on every attempt inflates cost and buries the error. A better pattern is to send the failing sub-object plus its path and ask for a replacement for that node only, splicing the result back in yourself. This keeps the repair turn small, keeps attention on the defect, and avoids the model rewriting fields that were already correct. Avoid letting the conversation accumulate. A repair loop that appends every failed attempt to a growing history pays for all of it on every subsequent turn and gives the model several wrong examples of its own output to anchor on. Constructing each repair turn freshly — original instruction, the (sub-)output, the error — is usually both cheaper and more accurate. ## Fix deterministically before you pay for a generation A surprising share of validation failures are mechanically repairable in code, and doing so is thousands of times cheaper than a model call: - Output wrapped in code fences or preceded by an explanatory sentence — extract the JSON span. - A number rendered as a numeric string, or a boolean as `"true"` — coerce where the target type is unambiguous. - Trailing commas or single quotes from a model in a permissive mood — a lenient parse pass. - Whitespace, casing or separator drift on a value whose canonical form is unambiguous. The rule of thumb: if a deterministic transformation cannot possibly change meaning, do it in code. Reserve model calls for failures that require judgment — a missing field, a wrong classification, a value that must be re-derived from the source. ## Diagnose the failure class before looping Not every validation failure is a repair candidate, and treating them uniformly is a classic mistake. - **Truncation.** If the response ended at the token limit, the object is incomplete through no fault of reasoning. The fix is a larger output allowance, a continuation, or a decomposed extraction — a repair prompt will just produce another truncated object. - **Schema defect.** If one field fails on a large fraction of requests, the loop is masking a design problem. Fix the schema — add an enum, clarify the format in the description, flatten the structure — and the repair traffic disappears from every future request. - **Source ambiguity.** If the model cannot fill a field because the source document genuinely does not contain it, no number of repair turns will conjure it. The right outcome is a null with a reason, or a human escalation — not a loop that eventually produces a plausible fabrication. ## Settings and expectations for the repair attempt Lower the sampling temperature for the repair turn: you want the model's most likely correction, not exploration. Keep the instruction narrow — "return only the corrected JSON object" — because a repair turn is an unusually strong invitation to add explanatory prose. And validate the repaired output with exactly the same validator; a repair that is accepted by a looser check defeats the whole arrangement. ## Know the shape of the success curve First-attempt repairs succeed at a high rate when the error message is specific, because most failures are small format slips. The second attempt succeeds far less often, because a failure that survived a precise error message is usually not a format slip at all — it is ambiguity, a missing fact, or a schema the model cannot satisfy. That curve is why repair budgets are small, and why the interesting design question is not how to retry harder but what to do when the budget runs out.