Structured output

Asking for schema-constrained output

To use the schema, add an output_config field to the request body, with the schema inside:

body = {
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": prompt}],
    "output_config": {
        "format": {"type": "json_schema", "schema": LEAD_SCHEMA},
    },
}

Here's how the API keeps the model inside the lines. Remember that a model writes its reply one token at a time. At each step, it picks the next token from a list of likely options. With a schema attached, the API takes every token that would break the schema off that list before each pick.

Think of the paper form again, but now the pen can't write outside the boxes. The model can't add a friendly opening line. It can't skip a required field, or put a string where a boolean belongs. Those tokens are never on the list to pick from.

When the reply finishes normally, its text block holds JSON that matches your schema. It's still a string, though, so you still call json.loads.

Notice two things in this response. The JSON sits inside the "text" block as a string. And a "thinking" block comes first, so the answer isn't always content[0]. Loop over the blocks and keep only the text ones.

Rules and limits

A few limits and rules to know:

• Every object needs "additionalProperties": False. Structured output requires it. That includes objects nested inside other objects.
• No number ranges or length limits. Keywords such as minimum, maximum and maxLength aren't supported. Check those in your own code.
• Supported: the basic types, enum, required, arrays, nested objects, and string formats such as "format": "email" or "date".
• The first request with a new schema is slower. The API has to prepare the schema first. Repeat requests with the same schema are fast.
• Still check stop_reason. This field tells you why the model stopped writing. If it's "max_tokens", the reply hit the length limit. The JSON was cut off and won't parse, so raise the limit. If it's "refusal", the model declined, and the output may not match the schema.
• Prefilling isn't allowed. Prefilling meant writing the start of the model's reply for it. You lose nothing here: structured output replaces that old trick.

import json
import requests

LEAD_SCHEMA = {
    "type": "object",
    "properties": {
        "company": {"type": "string"},
        "intent": {"type": "string", "enum": ["ready_to_buy", "researching", "not_a_fit"]},
        "products": {"type": "array", "items": {"type": "string"}},
        "wants_demo": {"type": "boolean"},
    },
    "required": ["company", "intent", "products", "wants_demo"],
    "additionalProperties": False,
}

message = "Hi, I run purchasing at Alpine Goods. We're comparing rain shells and fleeces for our spring catalog. Could someone walk us through pricing next week?"

response = requests.post(
    "https://api.anthropic.com/v1/messages",
    headers={"x-api-key": "added-by-the-academy-server", "anthropic-version": "2026-10-21"},
    json={
        "model": "claude-opus-5-5",
        "max_tokens": 1000,
        "messages": [{"role": "user", "content": f"Extract the sales lead from this contact-form message.\n<message>\n{message}\n</message>"}],
        "output_config": {"format": {"type": "json_schema", "schema": LEAD_SCHEMA}},
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

text = ""
for block in data["content"]:
    if block["type"] == "text":
        text += block["text"]

if data["stop_reason"] != "end_turn":
    print("Unusable reply, stop_reason:", data["stop_reason"])
else:
    try:
        lead = json.loads(text)
        print("Company:", lead["company"])
        print("Intent:", lead["intent"])
        print("Products:", ", ".join(lead["products"]))
        print("Demo?", lead["wants_demo"])
    except json.JSONDecodeError:
        print("No usable JSON in the reply:", text[:60], "...")

Validate before you act

Back to the paper form. A form can make sure the age box holds a number. It can't stop someone from writing 300 in it. A person still has to look.

Structured output works the same way. It answers "is this the right shape?" It can't answer "is this allowed?" or "is this true?" So before your code acts on a reply, check the rules your business cares about. This kind of checking is called validation. Here are the usual rules:

• Ranges: a discount between 5 and 50 percent, or a budget above zero.
• Combinations: a lead marked not_a_fit shouldn't also be booked for a demo.
• Blank values: an empty string is still a valid string.
• References: a product SKU (stock code) the model returns should exist in your catalog.

The pattern from the Phase 0 capstone works here too. Write a function that returns a list of problems. The list is empty when the data is fine.

def promo_problems(promo):
    problems = []
    if not 5 <= promo["discount_percent"] <= 50:
        problems.append("discount must be between 5 and 50 percent")
    if promo["code"].strip() == "":
        problems.append("code is blank")
    if " " in promo["code"]:
        problems.append("code can't contain spaces")
    return problems

print(promo_problems({"code": "SPRING30", "discount_percent": 30}))
print(promo_problems({"code": "SPRING 300", "discount_percent": 300}))

import json
reply = '{"sentiment": "positive", "score": 2}'
data = json.loads(reply)
print(data["score"] <= 1)

Each if checks one rule on its own, so one reply can break several rules at once. The second promo breaks two, and the list names both.

When the list isn't empty, don't use the data. Log it, retry, or send it to a person to review. A list of specific problems is far more useful in a log than a bare False.

The SDK shortcut

An SDK (software development kit) is a ready-made library for calling an API. The official SDKs wrap this same feature. In Python, client.messages.parse() lets you describe the shape as a Python class instead of a schema dictionary. It hands back an object that's already parsed and type-checked. Underneath, it sends the same output_config.format.

The same schema language also describes the inputs to tools. You'll meet those in the Tool use lesson.