CORE GUIDE
Structured output is an application contract
A JSON shape is useful only when the application validates both syntax and the meaning required by downstream code.
Mental model
Structured output turns free-form generation into a boundary contract, but the contract is incomplete until invalid and semantically impossible values are rejected.
Why it matters
Parsing JSON successfully is not the same as receiving a valid business object. Production systems need a boundary that catches missing fields, wrong enums, impossible combinations and version drift before generated data reaches databases, tools or user-visible actions.
01
From format to contract
A strong boundary has at least two layers: structural validation checks types and required fields, while semantic validation checks domain rules. Versioning and bounded repair then make failures explicit instead of silently coercing bad output.
02
Example: a valid but impossible order
The model returns valid JSON with quantity -3 and a shipping method that is forbidden for the destination. A parser accepts it; a schema may catch the negative number; semantic validation catches the destination rule. Each layer protects a different invariant.
Common failure modes
- Treating 'valid JSON' as equivalent to valid application data.
- Retrying the same prompt blindly after validation fails.
- Changing schemas without explicit version handling.
Engineering heuristics
- Validate structure and business semantics separately.
- Feed precise validation errors into a bounded repair attempt.
- Keep downstream side effects behind the validated contract boundary.
Takeaways
- 01Structure reduces ambiguity but does not eliminate semantic failure.
- 02Validation errors are evidence that should guide repair.
- 03Contracts belong at the application boundary, not only in the prompt.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.