Structured Outputs & JSON Schema Modes

Intermediate

Stop begging for valid JSON — enforce it

01 The Concept

If your prompt still contains three paragraphs pleading "respond ONLY with valid JSON, no markdown, no explanation…", you're solving a 2023 problem. Every major API now ships a structured-output / JSON-schema mode that constrains generation at the decoding level: the model literally cannot emit invalid JSON or unknown fields.

The prompt's job shifts: the schema handles shape, your prompt handles semantics — what each field means, how to decide values, what to do when information is missing. Put field-by-field decision rules in the prompt (or in the schema's `description` fields), and reserve an explicit place for uncertainty, like a `confidence` field or nullable values, so the model isn't forced to fabricate.

02 Weak vs. Strong

EX 01Support-ticket triage (schema + semantic rules)

Triage the support ticket below. A JSON schema is enforced separately with fields: category (enum: billing|bug|feature_request|account|other), priority (enum: p0|p1|p2|p3), sentiment (enum: angry|frustrated|neutral|positive), summary (string, ≤20 words), missing_info (array of strings). Decision rules: - p0 ONLY if: data loss, security issue, or a production system down for a paying customer - 'angry' requires explicit hostility; disappointment alone is 'frustrated' - category 'other' must include at least one missing_info entry explaining what would disambiguate - summary states the user's actual blocking problem, not their emotion TICKET: "Second time writing. Export has been spinning for 3 days and our quarterly report is due Friday. If this isn't fixed we're moving to Retool."

→ Why it works

Shape is the schema's job; every judgment call (what counts as p0, angry vs frustrated) has a written rule — that's where triage quality actually comes from.

EX 02Extracting contract facts with honest gaps

Extract fields from the contract excerpt below. Schema (enforced): each field is an object {value: string|null, quote: string|null, confidence: high|medium|low}. Fields: party_a, party_b, start_date (ISO), end_date (ISO), payment_terms, auto_renewal. Rules: - value must be supported by a verbatim quote from the excerpt; put that quote in 'quote' - if the excerpt doesn't state a field, value=null, quote=null, confidence=low — do NOT infer from typical contracts - dates written as '12 months from execution' → keep as written in value, confidence=medium EXCERPT: "This agreement between Vitae Inc. and BlueHarbor LLC commences January 5, 2026 and continues for twelve (12) months. Fees are payable net-45."

→ Why it works

Quote-anchored extraction with nullable values makes hallucinated fields structurally impossible to hide — every value must point at its evidence.

03 Key Points

01Use the API's schema/structured-output mode for shape; delete the 'ONLY valid JSON' pleading

02Prompt defines semantics: per-field rules, edge cases, and what 'unknown' looks like

03Make uncertainty representable: nullable fields, 'unknown' enums, confidence scores — or the model will invent

04Enums beat free strings for anything you'll branch on downstream

05Test with hostile inputs: empty text, wrong language, two answers in one sentence — schema guarantees shape, not sense

04 Model-Specific Notes

Claude supports structured outputs via tool-use schemas and a dedicated structured-output mode — both constrain shape hard. Put per-field guidance in the schema 'description' keys; Claude reads them like inline prompt text.

05 For Your Role

Even outside code: 'return a table with exactly these columns and use ✗ for anything not stated' is the same idea — fixed shape, honest gaps.

Next: Prompting Coding Agents →