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.
Worked example: extracting a candidate record
A hiring tool might extract a name, skills, source page, and confidence from a resume, but it should not infer protected characteristics or make a hiring decision from the model response. Missing fields should be represented as unknown, and evidence should point to the source page. A human should review uncertain records before they enter a search index. The schema defines shape; it does not define permission or fairness.
Code walkthrough
The JSON example represents a validated record with confidence, source page, and status. In code, parse it through a versioned schema, constrain confidence to a range, require a source when status is verified, and reject unexpected status values. Run semantic checks after parsing and escape values before rendering them. Keep the original response under controlled retention only when debugging justifies it.
Trade-offs to measure
Strict schemas protect downstream systems but can create more review states when source documents are incomplete. Flexible schemas preserve information but make consumers guess what a field means. Provider-native structured output can improve syntax while remaining probabilistic about facts. Prefer explicit unknown values to fabricated completeness, and measure review effort alongside validity and extraction accuracy.
Practical exercise
Define a version-one schema for a five-field extraction task. Test missing, null, extra, malformed, out-of-range, and contradictory values. Add one semantic rule that cannot be enforced by JSON alone. Create a version-two schema with one renamed field and write a migration or compatibility test. Confirm that invalid records cannot trigger an external write.
Sources and further reading
These primary or specialist references informed the concepts in this guide. Product details can change, so verify current documentation before implementation.