DS DevShelfHub Projects · AI tools
Tutorials / LangChain / Reference / Methods / .with_structured_output()
Method Chat models with structured output

.with_structured_output(): Reference Guide

By DevShelfHub

Guarantee model returns structured JSON matching schema.

What is .with_structured_output()?

.with_structured_output() wraps a chat model and constrains it to return data matching a given schema — either a Pydantic BaseModel class or a raw JSON Schema dict. It returns a new Runnable whose output type matches the schema class: calling .invoke() returns a validated Pydantic model instance rather than an AIMessage. This eliminates the brittle pattern of prompting a model to "respond in JSON" and then manually parsing and validating the output.

Under the hood, the method uses the most reliable mechanism each provider supports. For OpenAI and Azure OpenAI, it uses the response_format={type: "json_schema"} API (or function calling on older model versions). For Anthropic, it uses tool use. For Google Gemini, it uses response_schema. For providers that support neither, LangChain falls back to instructing the model in the system prompt and parsing the text output with a JSON parser — this fallback is less reliable and more prone to validation failures.

The schema argument can be a Pydantic v1 or v2 BaseModel class, a TypedDict class, or a dict following JSON Schema conventions. Pydantic models give you the richest validation — field descriptions, validators, optional fields with defaults, and nested models all work. Pass include_raw=True to get a dict with both the raw AIMessage and the parsed result, which is useful for debugging validation failures. When the model returns output that fails Pydantic validation, the method raises an OutputParserException — catch it and retry with a different prompt or schema simplification.

Use Cases

  • • Guaranteed JSON output
  • • Data extraction
  • • Form filling
  • • API response generation
  • • Type-safe parsing
  • • Validation enforcement

Key Features

  • ✓ Schema validation
  • ✓ Pydantic integration
  • ✓ Provider optimization
  • ✓ Type safety
  • ✓ Auto error handling
  • ✓ Format guarantee

When NOT to Use

For free-form text—use invoke(). Don't combine with OutputParser.

Notes

Provider support varies — OpenAI and Anthropic are most reliable

OpenAI's GPT-4o and GPT-4o-mini use native JSON schema mode, which strictly enforces the schema server-side. Anthropic Claude uses tool use for structured output. Older or less capable models fall back to prompt-based extraction, which is less reliable and may raise OutputParserException on validation failure. Test structured output end-to-end for each provider you target.

Add Field(description=...) to every field — the model reads them

Field descriptions are included in the JSON schema sent to the model. A field like confidence: float is ambiguous; confidence: float = Field(description="0.0–1.0 confidence score for the classification") constrains the model's understanding and produces far more consistent outputs. Treat schema descriptions as part of your prompt.

OutputParserException means the model returned invalid JSON or failed Pydantic validation

When structured output fails, catch OutputParserException and inspect the raw message with include_raw=True. Common causes: the model added explanatory text before the JSON, a required field was omitted, or an enum value outside the allowed set was returned. Simplify the schema or strengthen the system prompt to reduce failure rates.

Do not chain with an output parser — .with_structured_output() already parses

A common mistake is to compose structured_model | JsonOutputParser() in an LCEL chain. The output is already parsed into a Pydantic model or dict — adding a JsonOutputParser will either fail or double-parse. The returned Runnable's output is the Pydantic instance; use it directly.

Method Signature

python 
structured_model = model.with_structured_output(schema)

Parameters

Parameter Type Required Purpose
schema Type|dict Yes Pydantic model or dict schema

Return Value

Type:

Runnable

Description:

Model returning structured output

Example Output:

structured_model.invoke(input)

Code Examples

Extract data with Pydantic schema

python 
from pydantic import BaseModel
from langchain_openai import ChatOpenAI
class Person(BaseModel):
    name: str
    age: int
model = ChatOpenAI(model="gpt-4o-mini")
structured = model.with_structured_output(Person)
result = structured.invoke('Alice is 30 years old')
print(result.name, result.age)

Nested schema with Field descriptions

python 
from pydantic import BaseModel, Field
from typing import List, Optional
class Sentiment(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    confidence: float = Field(ge=0.0, le=1.0)
    topics: List[str]
    summary: Optional[str] = None
structured = model.with_structured_output(Sentiment)
result = structured.invoke("The product is great but shipping was slow")
print(result.sentiment, result.confidence)

Debugging with include_raw=True

python 
# include_raw=True returns both raw message and parsed output
structured = model.with_structured_output(Person, include_raw=True)
response = structured.invoke("Bob is 25")
print(response["raw"])      # AIMessage with raw content
print(response["parsed"])   # Person(name="Bob", age=25)
print(response["parsing_error"])  # None if successful

Common Mistakes

❌ Use OutputParser after with_structured_output()

✅ with_structured_output() handles parsing automatically

Related LangChain References

Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with .with_structured_output() and the wider framework.

.with_structured_output() FAQ

What does .with_structured_output() do in LangChain?

Guarantee model returns structured JSON matching schema. .with_structured_output() wraps a chat model and constrains it to return data matching a given schema — either a Pydantic BaseModel class or a raw JSON Schema dict. It returns a new Runnable whose output type matches the schema class: calling .invoke() returns a validated Pydantic model instance rather than an AIMessage. This eliminates the brittle pattern of prompting a model to "respond in JSON" and then manually parsing and validating the output. Under the hood, the metho…

Which LangChain classes support .with_structured_output()?

.with_structured_output() is available on Chat models with structured output. Pin your installed LangChain version and verify the method exists in that release before deploying.

When should I use .with_structured_output()?

Use .with_structured_output() when your LangChain chains, agents, or pipelines need the behavior described in this guide.

What does .with_structured_output() return?

.with_structured_output() returns a Runnable. Model returning structured output

Does .with_structured_output() have an async equivalent?

.with_structured_output() does not have a documented async variant. Avoid .with_structured_output() For free-form text—use invoke(). Don't combine with OutputParser.

Where can I explore more LangChain API reference pages?

Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.