Designing schemas the model fills well

A schema guarantees the shape of what comes back. It guarantees nothing about whether the values are right, and that gap is where the work is. This section is about designing schemas that get accurate answers rather than merely parseable ones: field order that lets the model reason before it commits, an escape hatch on every enum so it is never forced to choose wrongly, descriptions written as instructions because that is what they are, and asking for evidence your code can check. Each change is small, and together they move accuracy more than swapping models does.

Start with the smallest version#

A schema is a promise about shape. Here is the smallest useful one, for sorting support emails, written with Pydantic so the same class validates the result.

from typing import Literal
from pydantic import BaseModel

class Ticket(BaseModel):
    category: Literal["billing", "bug", "account", "other"]
    urgent: bool

Every change below makes this better at producing correct values, which is the part a schema alone does not guarantee.

Order fields the way you would think#

The model writes the JSON from left to right, one token at a time. If the first field is the verdict, it commits to the verdict before writing anything that supports it. Put the evidence first and the conclusion last, and the conclusion is written with the evidence already in view.

class Ticket(BaseModel):
    quote: str          # the sentence that shows what the customer wants
    category: Literal["billing", "bug", "account", "other"]
    urgent: bool

Every enum needs a way out#

If the only choices are billing, bug and account, an email about a job application will be forced into one of them. The model is not allowed to say none of these, so it guesses. Always include an escape value such as 'other' or 'unclear', and then count how often it is used. A rising share of 'other' tells you the categories no longer match reality.

Nullable, not missing#

For extraction, a value that is not in the source should come back as null, never invented. Making the key always present but allowing null is the clearest way to say that, and some strict schema modes require every key to be present anyway, so null is how 'not found' is expressed.

class Invoice(BaseModel):
    invoice_number: str | None   # null when the document has none
    total: float | None
    currency: Literal["EUR", "USD", "GBP"] | None

Descriptions are part of the prompt#

Field descriptions are sent to the model with the schema. Use them for the rules that belong to one field, so the main prompt stays short.

from pydantic import Field

class Invoice(BaseModel):
    total: float | None = Field(
        description="Amount due including tax, as printed. Null if not shown. "
                    "Do not add line items up yourself."
    )

Ask for evidence you can verify in code#

The most useful trick in extraction: for each important value, also ask for the exact text it came from. Then check in code that the text really appears in the document. A value whose quote is not in the source was probably invented.

class Extracted(BaseModel):
    value: str | None
    source_text: str | None

def grounded(f: Extracted, document: str) -> bool:
    if f.value is None:
        return True
    return f.source_text is not None and f.source_text in document

Know when to split#

Large schemas with deep nesting and dozens of fields get worse values than small ones. If a schema has grown past what you could fill in by hand in a minute, consider two calls: one to find the relevant part of the document, one to extract from it. Each can then be tested on its own.