Field guide / 8 min
Treat schema as user experience
Reliable shape still needs refusal, validation, and domain checks.
Structured Outputs can constrain model responses to a supplied JSON Schema. That removes a class of parsing failures, but it does not prove that values are true, useful, authorized, or safe to apply.
Working principles
Shape is not truth
Schema adherence verifies structure. Domain validation, source checks, and business rules still decide whether data is acceptable.
Refusal is a first-class state
A safety refusal does not necessarily follow your application schema. Give it an explicit UI and control-flow branch.
Version contracts
Name schema versions and migrate consumers deliberately. A prompt edit should not silently redefine production data.
Field procedure
- 01
Start from the consumer
Write the smallest object the next application step actually needs; omit explanatory fields that no consumer reads.
- 02
Constrain ambiguity
Use enums, required keys, bounds, and descriptions. Avoid unbounded maps when a finite list is known.
- 03
Handle every terminal state
Separate valid output, refusal, incomplete output, transport error, and local validation failure.
- 04
Apply domain validation
Check identifiers, dates, permissions, totals, references, and cross-field invariants after parsing.
- 05
Evaluate with fixtures
Keep representative inputs and assert both schema validity and task quality before changing prompts or models.
PASS / FAIL
Acceptance checklist
- Schema has an explicit version.
- Refusal has a product-state design.
- Business invariants run after parsing.
- Fixtures cover valid, edge, adversarial, and refused inputs.
WATCH / REJECT
Failure patterns
- Equating parse success with correctness.
- Making every field optional to avoid failures.
- Writing schema solely around the first model sample.