Structured Outputs
Use schemas and validation to turn probabilistic model responses into dependable application data.
Why structure helps
Free-form text is difficult to parse reliably and easy to misinterpret downstream. A schema defines fields, types, allowed values, optionality, and constraints that the application can validate. Structured output does not make the model correct, but it moves part of the problem from uncertain prose into explicit software checks. Use it whenever another component needs dependable data.
Design the schema
Name fields according to their business meaning and describe edge cases such as missing, unknown, or not-applicable values. Prefer enums and bounded numbers where the domain allows them. Avoid making every field required if the source may not contain it. Keep schemas small enough for the model to follow and stable enough that downstream code can evolve deliberately.
{
"name": "Ada Lovelace",
"confidence": 0.97,
"source_page": 3,
"status": "verified"
}Request and parse
Ask the provider for its structured-output mode when available, then parse the response with a schema library such as Pydantic. Treat invalid JSON, truncated output, wrong types, unknown values, and content that violates limits as failures. Preserve the raw response only under controlled retention when debugging requires it. Never let an unvalidated object reach a side-effecting function.
Recovery strategies
A failed parse may be recoverable through a bounded correction request, a safe retry with a clearer schema, or human review. Only retry when the operation is idempotent and the input is safe to send again. Do not silently drop fields or coerce dangerous strings into numbers. Return an explicit incomplete state when the system cannot establish a trustworthy result.
Semantic validation
A valid schema can still contain a false claim, wrong date, impossible quantity, or unauthorized target. Add domain checks for ranges, relationships, arithmetic, references, permissions, and evidence. Compare extracted values with source material when possible. Separate syntactic validity from semantic correctness in metrics and user messages so teams fix the right layer.
Adversarial and edge cases
Test missing fields, extra fields, nulls, long strings, Unicode, nested content, invalid enums, empty arrays, duplicate records, prompt injection inside values, and model refusals. Test schema evolution against old data and clients. Include examples where the correct answer is “unknown.” These cases reveal whether the integration is robust or only optimized for a neat demonstration.
Use structured data safely
Keep schemas versioned and attach the prompt, model, source, and validation result to each record. Use typed objects internally, but escape values when rendering or passing them to another system. Add human approval before financial, destructive, or external actions. Structured output is a reliable boundary only when the application validates, authorizes, and monitors what crosses it.