Validating and Parsing Structured Responses in Python

Defining a schema is only half the job - you also need to turn the response you get back into a usable Python object, and know what to do when that response isn't complete.

This page covers client.messages.parse(), the Pydantic-backed helper that does the validation and deserialization for you, plus the manual path with client.messages.create() for when you need more control.

Summary

client.messages.parse() is the recommended way to consume a structured output in Python: pass it a schema (typically from a Pydantic model), and it returns a response whose parsed_output attribute is already a validated instance of that model.

This replaces the manual sequence of extracting text from the response, calling json.loads(), and then constructing your own object from the dict.

You can still use client.messages.create() directly when you want the raw response content, for example to inspect stop_reason before deciding whether the output is even safe to parse.

Both paths use the same output_config.format schema underneath - parse() is a convenience layer, not a different API feature.

Recipe

Quick-reference recipe card - copy-paste ready.

from pydantic import BaseModel
from anthropic import Anthropic
 
class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str
 
client = Anthropic()
 
response = client.messages.parse(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": Invoice.model_json_schema()}},
    messages=[{"role": "user", "content": "Extract: Acme Corp billed $1,240.50 USD."}],
)
 
invoice: Invoice = response.parsed_output
print(invoice.vendor, invoice.total, invoice.currency)

When to reach for this:

• You already have (or want) a Pydantic model representing the data you're extracting.
• You want a typed object back, not a dict you have to index into.
• You're building a pipeline where the parsed value gets passed directly into other typed Python code.
• You want validation and parsing to happen in one step instead of two.

Working Example

from pydantic import BaseModel, ValidationError
from anthropic import Anthropic, APIStatusError
 
class SupportTicket(BaseModel):
    subject: str
    urgency: str
    customer_email: str
 
client = Anthropic()
 
def extract_ticket(raw_text: str) -> SupportTicket | None:
    try:
        response = client.messages.parse(
            model="claude-sonnet-5",
            max_tokens=1024,
            output_config={
                "format": {"type": "json_schema", "schema": SupportTicket.model_json_schema()}
            },
            messages=[{"role": "user", "content": f"Extract ticket fields from:\n\n{raw_text}"}],
        )
    except APIStatusError as e:
        print(f"API error: {e.status_code} {e.message}")
        return None
 
    if response.stop_reason == "max_tokens":
        print("Response was truncated before completing - not safe to trust.")
        return None
 
    if response.stop_reason == "refusal":
        print("Claude declined to produce a response for this input.")
        return None
 
    return response.parsed_output
 
 
ticket = extract_ticket(
    "From: jane@example.com\nSubject: Can't log in\n\n"
    "I've been locked out of my account since this morning, please help ASAP."
)
if ticket:
    print(ticket.subject, ticket.urgency, ticket.customer_email)

What this demonstrates:

• stop_reason is checked before trusting response.parsed_output, because a truncated or refused response is not guaranteed to have a usable parsed value.
• APIStatusError catches network/API-level failures separately from content-level issues like truncation or refusal.
• The function returns None on any failure path rather than letting an exception from a partially-formed response propagate unexpectedly.
• response.parsed_output is only read once every earlier guard has passed.

Deep Dive

How It Works

• client.messages.parse() sends the same request as client.messages.create(), with the schema built from your Pydantic model (or raw dict) passed via output_config.format.
• Once the response comes back, the SDK validates the returned JSON text against the schema and constructs an instance of the model you provided, exposing it as response.parsed_output.
• The underlying response object still has the same fields as a normal Message - stop_reason, usage, content - parsed_output is additive, not a replacement.
• Validation at this layer confirms the response matches the shape the schema described; it does not verify the values are factually correct.

create() vs. parse()

Handling a Response That Didn't Parse Cleanly

import json
from anthropic import Anthropic
 
client = Anthropic()
 
schema = {
    "type": "object",
    "properties": {"summary": {"type": "string"}},
    "required": ["summary"],
    "additionalProperties": False,
}
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=64,  # deliberately small - likely to truncate on a long answer
    output_config={"format": {"type": "json_schema", "schema": schema}},
    messages=[{"role": "user", "content": "Write an extremely detailed multi-paragraph summary."}],
)
 
raw_text = response.content[0].text
if response.stop_reason == "max_tokens":
    print("Truncated - do not attempt json.loads() on this, retry with more max_tokens instead.")
else:
    data = json.loads(raw_text)
    print(data["summary"])

• Using create() directly here makes the truncation check explicit and visible, which is useful when you want full control over the failure path rather than relying on parse()'s internal handling.
• Calling json.loads() on a known-truncated string will raise json.JSONDecodeError - checking stop_reason first avoids hitting that exception in the normal control flow.

Python Notes

from pydantic import BaseModel, field_validator
 
class Invoice(BaseModel):
    vendor: str
    total: float
 
    @field_validator("total")
    @classmethod
    def total_must_be_positive(cls, v: float) -> float:
        if v < 0:
            raise ValueError("total must be non-negative")
        return v

• Pydantic validators still run when client.messages.parse() constructs parsed_output - a schema-valid response that fails a custom validator raises a pydantic.ValidationError, which is a distinct failure mode from a malformed API response.
• This is useful for constraints the JSON Schema layer doesn't enforce (like numeric ranges), letting Pydantic catch what the schema-level guarantee can't.

Gotchas

• Reading response.parsed_output before checking stop_reason. On a truncated response, the parsed value may be missing or the parse step itself may have failed. Fix: check stop_reason != "max_tokens" (and != "refusal") before touching parsed_output.
• Assuming parse() and create() need different schemas. They use the exact same output_config.format schema - the only difference is what the SDK does with the response afterward. Fix: define the schema once and pass it to whichever call you use.
• Not catching pydantic.ValidationError when you have custom validators on the model. A schema-valid response can still fail a Pydantic-level constraint like a custom field_validator. Fix: wrap the parse() call in a try/except that catches both API errors and Pydantic validation errors if your model has custom validation logic.
• Treating a successful parse as proof the data is correct. Validation confirms shape and any Pydantic-level constraints, not that the extracted values are factually accurate. Fix: add a downstream review or spot-check step for anything high-stakes.
• Forgetting that create() still returns text you must json.loads() yourself. Developers sometimes expect create() to auto-parse the way parse() does. Fix: use parse() when you want the object; use create() only when you specifically want the raw text or more manual control over the response handling.

Alternatives

FAQs

data = json.loads(raw_text)
invoice = Invoice.model_validate(data)

Related

• Structured Outputs Basics - the first introduction to client.messages.parse.
• Defining a JSON Schema for output_config.format - how the schema this page parses is built.
• Handling Malformed or Truncated JSON Output - a deeper look at the stop_reason checks used throughout this page.
• Structured Output Field Types and Constraints Reference - what schema constructs are safe to rely on before you get to parsing.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.