Designing a JSON Schema
Shape the output to exactly what you need.
Designing a JSON Schema is a free Claude Architect lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Schema-Shaped Output
When you need Claude's answer in a precise structure, don't parse free text and hope. Pair tool_use with a JSON Schema: Claude fills a tool's input_schema and the API guarantees valid JSON with your required fields present.
This eliminates two whole classes of failure: syntax errors (missing commas, unescaped quotes) and missing fields. The schema IS the contract — design it well and downstream code never has to defend against malformed shapes.
The Tool Is the Schema
A structured-output "tool" doesn't have to call anything. It's just a named container whose input_schema describes the shape you want back. You define it, then read what Claude put in the tool call.
Give the tool a clear name and description — these still drive selection — but the real work is in the schema's properties and required list.
extract_invoice = {
"name": "extract_invoice",
"description": "Record the structured fields parsed from an invoice document.",
"input_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
},
}Force the Structure with tool_choice
If you want guaranteed structured output, don't leave it to chance. Set tool_choice to force a tool call:
"auto"— model picks text or a tool"any"— model MUST call some tool (guarantees structured output){"type":"tool","name":"X"}— force one specific tool
For single-schema extraction, forcing the exact tool by name is the cleanest path to a deterministic shape.
resp = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[extract_invoice],
tool_choice={"type": "tool", "name": "extract_invoice"},
messages=[{"role": "user", "content": invoice_text}],
)Required Means Always Present
The single most important schema rule: mark a field required ONLY if it is always present in the source. Never require a field that may be absent.
Why? A required field forces the model to emit a value. If the data isn't there, Claude will fabricate one to satisfy the contract. Optional-but-absent is honest; required-but-missing breeds hallucination.
Optional Fields, Done Right
For fields that may or may not appear — a discount line, a secondary contact, a due date — leave them OUT of required. Describe them clearly so Claude only fills them when the data genuinely exists.
A good description tells the model the input format and the absence rule, so it omits rather than invents.
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"due_date": {
"type": "string",
"description": "ISO 8601 date (YYYY-MM-DD). Omit entirely if no due date is stated."
},
},
"required": ["invoice_number", "total"]Enums Constrain the Output
When a field has a fixed vocabulary — status, category, priority — use an enum. This collapses messy free text ("paid", "PAID", "settled") into one canonical value your code can switch on.
Enums also reduce hallucination: the model must choose from the listed set instead of inventing a label.
"status": {
"type": "string",
"enum": ["draft", "sent", "paid", "overdue", "void"],
"description": "Current invoice status."
}Designing Enums for Extensibility
Rigid enums break when reality grows a new case. The architect's pattern: add an "other" value to the enum AND a free-text detail field to capture what "other" actually was.
Now your schema stays valid for unforeseen inputs, you don't lose information, and you can mine the detail field to decide if a new enum value is warranted.
"category": {
"type": "string",
"enum": ["hardware", "software", "services", "other"]
},
"category_detail": {
"type": "string",
"description": "If category is 'other', describe it here. Omit otherwise."
}Descriptions Do the Teaching
Field descriptions are mini-prompts. Vague keys produce vague output. Spell out the format, give an example, and state edge-case handling right in the schema.
This is the structured-output equivalent of explicit criteria beating vague instructions: "ISO 8601 date, omit if absent" beats a bare due_date: string every time.
"line_items": {
"type": "array",
"description": "One object per billed line. Empty array if none.",
"items": {
"type": "object",
"properties": {
"sku": {"type": "string", "description": "e.g. 'ABC-1024'"},
"qty": {"type": "integer"},
"unit_price": {"type": "number"}
},
"required": ["qty", "unit_price"]
}
}Build in Self-Verification
Great schemas help you catch errors. To verify arithmetic, extract BOTH a calculated and a stated value, then compare them in code.
For example, capture stated_total (printed on the doc) alongside the line items you can sum yourself. A mismatch flags an extraction or document error before it propagates downstream.
"stated_total": {
"type": "number",
"description": "The grand total exactly as printed on the invoice."
}
# In code:
# calc = sum(li['qty'] * li['unit_price'] for li in items)
# if abs(calc - data['stated_total']) > 0.01: flag_discrepancy()Validate, Then Retry with Feedback
The schema guarantees JSON shape, not business correctness. Layer Pydantic-style validation on top. When it fails on a format / structural / arithmetic error, retry — but feed the model what went wrong.
Send the original document, the wrong output, and the exact validation error. That's retry-with-feedback. Note: retrying does NOT help when information is simply absent from the source — no amount of re-asking conjures missing data.
messages = [
{"role": "user", "content": original_doc},
{"role": "assistant", "content": wrong_output},
{"role": "user", "content":
f"Validation failed: {error}. Re-emit corrected JSON."},
]
# Retry fixes format/arithmetic bugs, not missing facts.Capture Provenance in the Schema
For extraction you'll defend later, design fields that preserve provenance: where each claim came from. Keep claim-to-source mappings — source name, quote, page or date.
This turns a black-box extraction into an auditable one, and lets you annotate conflicting values (often a date difference) instead of silently picking one.
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {"type": "string"},
"source_quote": {"type": "string",
"description": "Verbatim text supporting this value."},
"source_page": {"type": "integer"}
},
"required": ["value", "source_quote"]
}
}Quick Check: Optional Field
You're extracting purchase orders. Some POs list a discount_code, but most do not. How should the schema treat discount_code?
Recap: Shaping the Output
Key takeaways for designing a JSON Schema:
- tool_use + JSON Schema kills syntax errors and enforces required fields.
- Force shape with
tool_choice:"any"for some tool,{"type":"tool","name":"X"}for a specific one. - Mark
requiredONLY for always-present fields — requiring an absent field causes fabrication. - Use enums for fixed vocabularies; add
"other"+ a detail field for extensibility. - Descriptions teach format, examples, and edge cases.
- Extract calculated AND stated values to self-verify; validate, then retry-with-feedback for format errors (not for absent info).
- Capture provenance for auditable, defensible extraction.
Frequently asked questions
Is the “Designing a JSON Schema” lesson free?
Yes — the full text of “Designing a JSON Schema” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.
What will I learn in “Designing a JSON Schema”?
Shape the output to exactly what you need. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Claude Architect?
No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Designing a JSON Schema” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Claude Architect lesson?
Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.