4.3 Structured output via tool_use and JSON schemas
Tool use with a JSON Schema is the most reliable approach for guaranteed schema-compliant output — it eliminates JSON syntax errors. See also structured outputs.
- TypeScript
- Python
const extractInvoice: Anthropic.Tool = {
name: "extract_invoice",
description: "Records the fields extracted from a single invoice document.",
input_schema: {
type: "object",
properties: {
invoice_number: { type: "string" },
// Nullable: the model returns null instead of fabricating a value.
po_number: { type: ["string", "null"] },
currency: { type: "string", enum: ["USD", "EUR", "GBP", "other"] },
currency_other_detail: { type: ["string", "null"] },
document_type: {
type: "string",
enum: ["invoice", "credit_note", "receipt", "unclear"],
},
stated_total: { type: ["number", "null"] },
calculated_total: { type: ["number", "null"] },
conflict_detected: { type: "boolean" },
line_items: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" },
unit_price: { type: "number" },
},
required: ["description", "quantity", "unit_price"],
additionalProperties: false,
},
},
},
required: ["invoice_number", "document_type", "conflict_detected", "line_items"],
additionalProperties: false,
},
};
const response = await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
tools: [extractInvoice],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: documentContent }],
});
const block = response.content.find((b) => b.type === "tool_use");
const extracted = block?.type === "tool_use" ? block.input : null; // already validated JSON
extract_invoice = {
"name": "extract_invoice",
"description": "Records the fields extracted from a single invoice document.",
"input_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
# Nullable: the model returns null instead of fabricating a value.
"po_number": {"type": ["string", "null"]},
"currency": {"type": "string", "enum": ["USD", "EUR", "GBP", "other"]},
"currency_other_detail": {"type": ["string", "null"]},
"document_type": {
"type": "string",
"enum": ["invoice", "credit_note", "receipt", "unclear"],
},
"stated_total": {"type": ["number", "null"]},
"calculated_total": {"type": ["number", "null"]},
"conflict_detected": {"type": "boolean"},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"quantity": {"type": "number"},
"unit_price": {"type": "number"},
},
"required": ["description", "quantity", "unit_price"],
"additionalProperties": False,
},
},
},
"required": [
"invoice_number",
"document_type",
"conflict_detected",
"line_items",
],
"additionalProperties": False,
},
}
response = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
tools=[extract_invoice],
tool_choice={"type": "tool", "name": "extract_invoice"},
messages=[{"role": "user", "content": document_content}],
)
block = next((b for b in response.content if b.type == "tool_use"), None)
extracted = block.input if block else None # already validated JSON
tool_choice for extraction
| Setting | Guarantee | Use when |
|---|---|---|
{"type": "auto"} | None — the model may return text instead of calling a tool | Conversational flows |
{"type": "any"} | A tool will be called; the model picks which | Several extraction schemas and the document type is unknown |
{"type": "tool", "name": "extract_metadata"} | That tool runs | Force a required first step before enrichment tools |
Syntax errors vs semantic errors
Strict JSON schemas via tool use eliminate syntax errors. They do not prevent semantic errors:
- line items that do not sum to the stated total
- a value placed in the wrong field
- a plausible-looking but fabricated date
Semantic correctness needs validation logic — see 4.4.
Schema design rules
| Rule | Reason |
|---|---|
| Make a field optional / nullable when source documents may not contain it | A required field pressures the model to fabricate a value to satisfy the schema |
Add an "unclear" enum value | Gives ambiguity somewhere to go other than a wrong guess |
Add "other" + a detail string | Extensible categorization without reopening the schema |
| Include format normalization rules in the prompt alongside the strict schema | The schema constrains shape, not source formatting inconsistency |
Preparation exercise 3 — Structured data extraction pipeline
Objective: JSON schema design, tool_use for structured output, validation-retry loops, batch processing.
- Define an extraction tool whose schema has required and optional fields, an
enumwith"other"+ detail string, and nullable fields for information that may be absent. Process documents where fields are genuinely missing and verify the model returnsnullrather than fabricating. - Implement a validation-retry loop: on Pydantic or JSON Schema validation failure, send a follow-up containing the document, the failed extraction, and the specific validation error. Track which errors are resolvable via retry (format mismatches) and which are not (information absent from source).
- Add few-shot examples for varied document formats — inline citations vs bibliographies, narrative descriptions vs structured tables — and verify improved handling of structural variety.
- Design a batch strategy: submit 100 documents via the Message Batches API, handle failures by
custom_id, resubmit failures with modifications (chunk oversized documents), and compute total processing time against an SLA. - Implement human review routing: field-level confidence scores from the model, low-confidence extractions to human review, and accuracy analysed by document type and field.
Reinforces: Domain 4, Domain 5
Quiz
- Question 1
Your pipeline asks for JSON in the prompt and parses whatever comes back. Roughly 4% of responses fail to parse: a sentence before the object, a stray code fence, an unquoted key. Each failure costs a second call and the volume is 100,000 documents a month. Which change eliminates this class of failure rather than reducing it?
- Question 2
Your pipeline exposes three extraction tools — extract_invoice, extract_contract and extract_receipt — and the document type is not known before the call. Occasionally the model replies with a prose description of the document and calls nothing, and that response has to be thrown away. Which configuration fixes it without deciding the document type on the model’s behalf?
- Question 3
Your invoice schema marks vendor_tax_id as required. On documents that do not contain a tax ID, extractions come back with plausible, correctly formatted, invented values that pass every syntactic check. What is the fix?
- Question 4
Your document_type enum has six values. About 4% of incoming documents are none of them, and the model assigns the nearest value, which corrupts downstream routing. New document types appear a few times a year. Which schema design handles this?
Links
- https://platform.claude.com/docs/en/build-with-claude/structured-outputs
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
- https://code.claude.com/docs/en/agent-sdk/structured-outputs
- https://en.wikipedia.org/wiki/JSON_Schema