Output contracts

Getting a guaranteed object back is machinery, and it is the easy half. This lesson is the design question that comes first: what shape should the contract be? Most of the reliability people chase with prompt wording is available for free in the schema. The mechanics, and what still gets past them, are in the next lesson.

1.The ladder from asking to guaranteeing

There are four rungs between "I would like JSON" and "this response cannot be the wrong shape".

Most people stop at rung 1, get burned, and write a parser. Rung 2 costs a few tokens and often fixes the drift on a small task. Rung 4 is the one that deletes the parser, and as of October 2026 it comes in two forms: a JSON output format (output_config.format), or strict: true on a tool definition.

One dated warning: forcing a tool call with tool_choice used to be the standard route to a guaranteed shape. As of September 2026 that request returns a 400 on claude-sonnet-5-5; it still works on some older models, so check the one you pin. Where you want a real function call, keep tool_choice on auto, add strict: true, and tell the model in the prompt when the tool applies. The guarantee comes from strict or the output format, not from tool use itself.

The caveat that matters more than any of this: a guaranteed shape is not a guaranteed answer. The schema says total_minor_units is an integer. It does not say it is the integer on the invoice. Structure and truth are separate problems, and the schema only solves the first.

2.Closed sets are the cheapest accuracy you can buy

Every free-text field is an invitation to a synonym. Declare status as a string and you collect paid, Paid, settled, payment received — four spellings of one fact, and your if status == "paid" is wrong three times out of four.

An enum collapses most of that into one line. It also forces you to decide what the categories actually are, which is usually where the real ambiguity was hiding while the model absorbed it silently.

An enum closes the set but not the case; compare case-insensitively. Structured outputs in practice shows the failure.

The decoder cannot enforce numeric ranges or string lengths; Structured outputs in practice has the table of what it drops, and Validating what comes back has the check.

The confidence row is on almost every first draft. A model's self-reported score is generated like every other token and is not calibrated against anything. A quote you can search the source for is worth far more, because your code can verify it.

3.Name the fields, fix the order, define unknown

Name them precisely. issue_date and due_date, not date. The field name is an instruction, and it sits right where the model needs it. If you write a sentence explaining a field, rename the field and delete the sentence.

Fix the order, and put evidence first. The model generates left to right, so a field produced early is in context for the later ones. Put the quote before the label and the label is produced with the quote already on the page, the same mechanism as Thinking out loud. The size of the effect is task-dependent, so order the fields well, then measure. One detail from the vendor page: output comes back with required properties first, in schema order, then optional ones. Mark everything required to keep your order.

{
  "source_quote": "...",
1  "invoice_number": "...",
  "issue_date": "...",
  "total_minor_units": ...,
  "currency": "..."
}2

Name that first field source_quote, not reasoning. A field called reasoning, trace or thinking can draw a reasoning_extraction refusal on Sonnet 5.5 and other current Claude models, and that category is billed even when no output arrives (as of September 2026). A quote or a short explanation is fine.

Define what unknown looks like. This stops invention. A model asked for a field the document does not contain will produce a plausible value, because plausible text is the only thing it makes. Give it a legal way to say nothing: null for absent, not an empty string and not "N/A" beside "unknown". Where unknown is a category, put it in the enum, because a four-value decision with no escape hatch is a three-value decision plus a guess.

A schema without a defined unknown is a schema that asks the model to make something up.

Here is the whole invoice contract as one call, the worked example for this lesson. The parameter spellings are copied from the vendor docs as of October 2026, not run here, so try them on your SDK version first.

import json
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"   # as of October 2026

def text_of(resp) -> str:
    return "".join(b.text for b in resp.content if b.type == "text")

INVOICE = {
    "type": "object",
    "properties": {
        # Evidence first: generated before the values it supports.
        "source_quote": {"type": ["string", "null"]},
        "invoice_number": {"type": ["string", "null"]},
        "issue_date": {"type": ["string", "null"], "description": "YYYY-MM-DD"},
        "total_minor_units": {"type": ["integer", "null"], "description": "Cents. 1204.00 USD is 120400."},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP", "unknown"]},
    },
    # Every field required, so the order above is the order you get.
    "required": ["source_quote", "invoice_number", "issue_date", "total_minor_units", "currency"],
    "additionalProperties": False,
}

resp = client.messages.create(
    model=MODEL,
    max_tokens=2000,   # thinking is on by default and counts against this
    system="Read the invoice. Use null for anything not stated. Never infer a value.",
    output_config={"format": {"type": "json_schema", "schema": INVOICE}},
    messages=[{"role": "user", "content": "<invoice>...</invoice>"}],
)

# The schema holds only for a finished answer: a refusal or a cut-off may not match it.
if resp.stop_reason != "end_turn":
    raise RuntimeError(f"no usable answer: {resp.stop_reason}")
invoice = json.loads(text_of(resp))   # no fence to strip, no regex

Nothing in that prompt asks nicely for anything. Every rule that could have been a sentence is a field name, a type, an enum or a null, and the system prompt exists only for the one rule a schema cannot express: what to do about missing values.

When not to use a contract. Skip it for free-form text, such as a reply email, where forcing fields strips the writing. Skip it when you need a real function call, which is tool use with strict, not an output format. Be careful when the task needs working out. With JSON as the only text, the working can happen only in thinking, and Anthropic's Sonnet 5.5 guide reports, as of October 2026, that at low or medium effort the model often skips it and accuracy drops on multi-step tasks (vendor-reported, no numbers). A closing line telling it to think the problem through, or a higher effort, is the vendor's fix. Steering how much it thinks has the detail.

Next: the shape is now the decoder's job, and Structured outputs in practice covers the schema limits, the SDK helper, and what still gets past the contract.