Skip to main content

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.

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

tool_choice for extraction​

SettingGuaranteeUse when
{"type": "auto"}None — the model may return text instead of calling a toolConversational flows
{"type": "any"}A tool will be called; the model picks whichSeveral extraction schemas and the document type is unknown
{"type": "tool", "name": "extract_metadata"}That tool runsForce a required first step before enrichment tools

Syntax errors vs semantic errors​

The boundary the exam tests

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​

RuleReason
Make a field optional / nullable when source documents may not contain itA required field pressures the model to fabricate a value to satisfy the schema
Add an "unclear" enum valueGives ambiguity somewhere to go other than a wrong guess
Add "other" + a detail stringExtensible categorization without reopening the schema
Include format normalization rules in the prompt alongside the strict schemaThe 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.

  1. Define an extraction tool whose schema has required and optional fields, an enum with "other" + detail string, and nullable fields for information that may be absent. Process documents where fields are genuinely missing and verify the model returns null rather than fabricating.
  2. 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).
  3. Add few-shot examples for varied document formats — inline citations vs bibliographies, narrative descriptions vs structured tables — and verify improved handling of structural variety.
  4. 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.
  5. 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​

  1. 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?

  2. 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?

  3. 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?

  4. 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?