Diseño de un esquema JSON

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

You're extracting purchase orders. Some POs list a discount_code, but most do not. How should the schema treat discount_code?

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 required ONLY 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.