6.3 — Output Handling

CCDV-F Domain 6 · Task 6.3

What You Need to Know

Structured output is a reply in a fixed shape (usually JSON matching a schema). Well-formed = parses and matches the shape. Correct = values are right.

Three Ways to Produce Structured Output

Method	Enforcement
JSON outputs (output_config.format with json_schema)	Strongest — constrained decoding; schema-compliant guaranteed on completed responses
Strict tool use (strict: true on tool definition)	Constrained decoding on tool names and inputs
Instruction-plus-example JSON	Fallback — relying on the model honouring a request

Python SDK: client.messages.parse(...) with a Pydantic model → response.parsed_output. First request with a new schema pays grammar-compilation latency; compiled grammars cache 24 hours.

The Schema Is Not the Validator

Parsing answers “is this well-formed?”. Validation answers “is this right?”. Structured outputs settle the first. The supported JSON Schema subset does not support numerical constraints (minimum/maximum), string constraints (minLength/maxLength), recursive schemas, or complex enums. additionalProperties must be false.

Four validation checks (yours):

1. Structural — required fields, types, enums (compare enums case-insensitively)
2. Range and plausibility — numbers inside domain bounds, dates in process window
3. Cross-field consistency — total equals sum of parts; status compatible with fields
4. Referential — identifiers naming real things, checked against the issuing system

On failure: raise with the raw response body and request id. Never substitute a default.

Check stop_reason Before the Payload

max_tokens / model_context_window_exceeded → truncated. refusal → declined (still HTTP 200). Never take everything between the first and last braces — succeeds on truncated output and prose-wrapped JSON.

Scepticism Towards Confident Output

Tone carries no information about accuracy. Give permission to decline with exact machine-detectable wording. For long documents, extract word-for-word quotes first. Citations feature (citations.enabled on documents) guarantees valid pointers — does not combine with structured outputs.

When Validation Fails

Re-ask with the specific validation errors attached. An identical re-ask is the weakest move.