Structured Output & JSON with Claude, Explained

Two approaches: prompted JSON vs tool-forced schema

There are two broad strategies for getting structured output. The first is prompted JSON: you ask, in natural language, for the model to reply with JSON matching a described shape. The second is tool-forced schema: you define a tool whose input_schema is your target structure and require the model to call it, so the model's arguments are your structured data.

Prompted JSON is quick and fine for a throwaway script. But the more your downstream code depends on the exact shape, the more you want the schema itself to be the contract — which is what tool use gives you. Check the Claude docs for the current tool-use request format, since field names and options evolve.

Forcing output with tool_choice

Defining a tool is not enough on its own — by default the model decides whether to call it. To guarantee structured output, set tool_choice to require your specific tool. Now the model cannot answer in free prose; it must return arguments that satisfy your schema. This turns 'please reply with JSON' into a structural guarantee rather than a polite request.

{
  "model": "claude-...",
  "tools": [
    {
      "name": "record_invoice",
      "description": "Extract structured fields from an invoice.",
      "input_schema": {
        "type": "object",
        "properties": {
          "invoice_number": { "type": "string" },
          "total_amount":   { "type": "number" },
          "currency":       { "type": "string", "enum": ["USD", "EUR", "INR"] },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "description": { "type": "string" },
                "amount":      { "type": "number" }
              },
              "required": ["description", "amount"]
            }
          }
        },
        "required": ["invoice_number", "total_amount", "currency"]
      }
    }
  ],
  "tool_choice": { "type": "tool", "name": "record_invoice" }
}

Reliability techniques

Forcing the shape gets you most of the way; a few habits close the rest of the gap between 'usually works' and 'safe in production.'

• Make the schema strict: use enums, types, required arrays, and formats so fewer wrong values are even expressible.
• Describe every field: put a clear description on each property; the model reads them, and good descriptions cut ambiguity.
• Instruct for the unknown: give an explicit rule for missing data (for example null) so the model does not invent a plausible value.
• Keep instructions and schema consistent: if the prose and the schema disagree, you invite drift — make them say the same thing.
• Handle refusals and truncation: a stop for max_tokens can cut a tool call mid-object, so check stop_reason and re-request when needed.
• Set enough output headroom: nested JSON is verbose; reserve enough output tokens for the whole structure to complete.

The trap: schema-valid is not semantically correct

This is where teams get burned. Because the JSON parses and matches the schema, it looks trustworthy — a green check from your validator. But schema validation only checks structure and types. It cannot tell you whether total_amount actually matches the invoice, whether the invoice_number was read correctly, or whether a line item was quietly invented. A confidently wrong number is still perfectly valid JSON.

Layered validation in practice

A robust pipeline validates in layers, cheapest and most structural first, then semantic. Each layer catches a different class of failure.

• Layer 1 — Structural: parse the JSON and validate it against the schema (types, required fields, enums). Reject or retry on failure.
• Layer 2 — Semantic and referential: check values against the source — do the line items sum to the total? Does the invoice_number appear in the document? Are dates plausible?
• Layer 3 — Business rules: apply domain constraints your schema cannot express, such as totals within an expected range or currency matching the vendor's country.
• Layer 4 — Confidence and escalation: on low-confidence or failed checks, route to a human or a second-pass verification rather than silently accepting.

The point is that the forced schema handles Layer 1 for you and nothing more. Layers 2 through 4 are where correctness actually lives, and they are code you write against the source of truth — not something the model or the schema can guarantee.