Structured output and schema validation

When code depends on a model's output, free text is fragile. Ask for structured output and validate it before using it.

Define the shape

In Python, Pydantic models describe the shape and check it for you.

from typing import Literal
from pydantic import BaseModel, Field

class Action(BaseModel):
    kind: Literal["search", "answer", "escalate"]
    query: str | None = None
    confidence: float = Field(ge=0, le=1)

action = Action.model_validate_json(model_output)

If the output does not match, validation raises an error with a clear message.

Prefer constrained fields

Use enums and literals for fixed choices, numeric ranges for scores, and lengths for text. The tighter the schema, the fewer unexpected values reach the rest of your code. Many model APIs can also enforce a schema during generation, which reduces failures further.

Repair, but with a limit

When validation fails, send the error back to the model and ask for a corrected version. This works well for small mistakes. Allow two or three attempts, then fail the step with a clear error. An unbounded repair loop can burn tokens forever.

Validate meaning, not just format

A response can match the schema and still be wrong. Check the things the schema cannot, such as whether an id exists, whether a date is in the future, or whether a requested table is allowed.

Fail early

It is much easier to debug a validation error at the boundary than a strange failure five steps later.