Required vs Optional/Nullable Fields

Structured output with tool_use and a JSON Schema eliminates syntax errors and lets you enforce required fields. But that power has a sharp edge.

The exam-critical rule for this lesson: mark a field required only if it is always present. Never require a field that may be absent.

Why? When a field is required, the model must emit a value for it. If the source data doesn't actually contain that value, the model has no choice but to fabricate one to satisfy the schema. A required field is a promise the model will keep even when it shouldn't.

A JSON Schema's required array is a hard constraint, not a hint. The model cannot return a structurally valid object while omitting a required key.

Consider extracting a customer's phone_number from a support email that never mentions a phone number. If phone_number is required, the model must produce something — and a plausible-looking but invented number is worse than no number at all, because nothing downstream can tell it apart from a real one.

The fix is structural: make optional fields optional, so the model can legitimately leave them out when the information is absent.

Here is an extraction tool that marks every field as required. The email below has no phone number — yet the schema forces the model to invent one.

This is the anti-pattern. Read required carefully: it lists fields that may genuinely be missing from real inputs.

Keep in required only the fields that are always present. Everything that may be absent stays out of required — the model can then omit it honestly.

Notice name and email stay required because every support ticket has them, while phone_number drops out of the list.

There are two ways to let a field be "missing", and they mean different things:

• Optional — the key is simply omitted from required. The model may leave the key out of the object entirely.
• Nullable — the key is always present but its type allows null, signalling "this slot was checked and found empty."

Optional answers "did the model report on this field at all?" Nullable answers "the model looked, and the value is explicitly absent." Choose nullable when a downstream consumer needs every key present for a stable shape.

To make a field nullable, allow null as one of its types. With structured outputs you typically express this with anyOf (a supported keyword) combining the real type and null.

Here phone_number is always emitted as a key, but its value is null when the email contains no number — an honest "empty", not a fabricated digit string.

A nullable type permits null, but the model still decides when to use it. Make the intent explicit in the field description: tell the model to return null rather than guess.

This pairs the structural guarantee (the type allows null) with a behavioural one (the description says when to use it). The schema defines the shape; the description steers the judgment.

The same fabrication risk appears with enums. If a field must be one of a fixed set of values and the real input doesn't match any of them, a strict enum forces the model to pick the closest wrong answer.

The exam-recommended pattern for extensibility: include an "other" value in the enum plus a free-text detail field. This gives the model an honest place to land when reality exceeds your enum — instead of misclassifying.

When validation fails, retry-with-feedback is powerful — you resend the original document, the model's wrong output, and the exact validation error to fix format, structural, or arithmetic mistakes.

But retry does not help when the information is simply absent from the source. If the phone number isn't in the email, no amount of re-prompting will conjure a correct one. The right design lets the field be absent in the first place — required-and-missing is a schema bug, not a transient error to retry.

For values that should be present and verifiable, a complementary technique is self-correction: extract both a calculated_total and a stated_total so a mismatch surfaces a discrepancy you can catch.

But self-correction detects errors in present data; it cannot validate a field that was never in the source. The first line of defense against fabrication is still the schema itself: don't require what may be absent. Use Pydantic-style validation on the result to enforce these invariants in code.

One more architect-grade distinction: a valid empty result ("the email has no phone number") is not the same as an access failure ("the extraction tool errored").

A nullable field cleanly represents the first case. Don't model a genuine absence as an error to retry, and don't silently suppress a real failure as null. Make the schema say which is which: null for legitimately empty, a separate error path for access failures. Clear, structured signals downstream beat ambiguous ones.

Apply the rule to a realistic extraction scenario.

Key takeaways:

• Require only always-present fields. Requiring a possibly-absent field forces the model to fabricate a value.
• Optional = key may be omitted; nullable = key always present, value may be null. Pick nullable when consumers need a stable key set.
• Pair nullable types with a description that says "return null if absent — don't guess."
• For closed value sets, add an "other" enum value plus a free-text detail field for extensibility.
• Retry-with-feedback fixes format/structural/arithmetic errors, not absent information. Self-correction detects discrepancies in present data, not missing fields.
• Keep a valid empty result distinct from an access failure — never silently suppress either.