Validators and Retry Feedback

A schema check confirms that the output has the right shape: the required keys are present, the types match, and the array is not empty. It does not confirm that the values are meaningful. A validator that only checks structure will pass outputs where confidence is "high" but the extracted invoice_total is negative, or where category is a valid enum value but plainly wrong for the input. This lesson covers how to write validators that catch those semantic errors, and how to phrase retry feedback so that the next attempt fixes the problem rather than producing a different wrong answer. By the end of this lesson, we will be able to:

• Distinguish structural validation from semantic validation and explain why both are necessary

• Write a validator that catches field-level semantic errors in extracted output

• Identify the difference between generic retry wording and specific retry feedback

• Implement a retry loop with a feedback message that names the exact error

Structural vs. semantic validation

Structural validation checks the form of the output. Semantic validation checks whether the values are coherent, consistent, and correct given the input.

The distinction matters because Claude almost never returns malformed JSON after output-format techniques are applied. The errors that reach production are semantic: the right keys, the wrong values. A few examples of outputs that pass structural validation but fail semantically:

The validator must encode the rules that make values meaningful, not just the rules that make them structurally ...