Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 32 ยท Models, Prompts and Parsers

Structured Output

Get reliable typed data from a model with with_structured_output: Pydantic schemas, TypedDict and JSON Schema, extraction patterns, enums, nested data and validation failures.

Asking a model to "reply in JSON" and then hoping works most of the time, and "most of the time" is not good enough for software. Modern providers support structured output: you give the API a schema, and the model is constrained to produce data that matches it. LangChain exposes this through one method, model.with_structured_output(schema), which returns a new Runnable that gives you Python objects instead of text.

The basic pattern

Python
from pydantic import BaseModel, Field
from langchain.chat_models import init_chat_model

class Movie(BaseModel):
    """Facts about a movie."""
    title: str = Field(description="Official title")
    year: int = Field(description="Release year")
    genres: list[str] = Field(description="One to three genres")

model = init_chat_model("openai:gpt-4o-mini", temperature=0)
structured = model.with_structured_output(Movie)

movie = structured.invoke("Tell me about the first Toy Story film.")
print(movie)            # Movie(title='Toy Story', year=1995, genres=['animation', 'comedy'])
print(movie.year + 1)   # 1996, a real int

This is read-only here, but notice what changed compared with a parser: no format instructions in the prompt, no JSON cleaning, and the result is a validated Movie. The class docstring and the Field(description=...) texts are sent to the model as part of the schema, so good descriptions directly improve accuracy.

Which schema types work

Schema You get back Notes
Pydantic BaseModel A validated model instance Best default: validation, defaults, nesting
TypedDict A plain dict Light; no runtime validation
JSON Schema dict A plain dict When the schema comes from elsewhere
Python dataclass An instance (provider-dependent) Less common

Under the hood LangChain picks the provider's best mechanism, such as a native JSON-schema response format or a forced tool call, so your code does not change per provider. Pass include_raw=True to receive both the raw AIMessage and the parsed result, useful when you also want token usage or need to debug.

What a schema looks like (runnable)

Pydantic can print the exact JSON Schema that gets sent to the model, and it runs in the browser, so you can see how descriptions and types travel.

Python Real Pydantic: the schema the model receives

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Validation as a safety net (runnable)

A schema stops many mistakes, but you still validate the result, especially numbers and enumerations. This runnable block simulates three replies from a model and shows what Pydantic accepts and rejects. The replies are hard-coded; only the validation is real.

Python Real Pydantic: validating simulated model replies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Literal[...] (or an Enum) restricts a field to fixed choices, the right tool for classification. Field(ge=1, le=5) bounds numbers. Both are also sent to the model, so it knows the rules before answering.

Extraction: lists and nesting

Structured output shines for information extraction: pulling facts out of free text. Nest models, and wrap a list in a container model so the model can return several items:

Python
class Person(BaseModel):
    name: str
    role: str | None = Field(default=None, description="Job title if stated")

class Meeting(BaseModel):
    date: str | None = Field(default=None, description="ISO date if mentioned")
    attendees: list[Person]

extractor = model.with_structured_output(Meeting)
extractor.invoke(
    "On 2026-03-04 Ana (designer) and Luis met with Priya, our CTO, to plan the launch."
)

Give optional fields a None default and say so in the description, otherwise the model may invent a value to satisfy a required field. That is the main failure mode of extraction: made-up data to fill a gap.

Python Real Pydantic: nested models and optional fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Structured output inside a chain

with_structured_output returns a Runnable, so it composes like any model:

Python
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "Extract the ticket details. Do not guess missing information."),
    ("human", "{email}"),
])
chain = prompt | model.with_structured_output(Ticket)
ticket = chain.invoke({"email": "Hi, I got billed twice and it's urgent!!"})

Many teams put a Pydantic class in a shared module and use it as the contract between the LLM step and the rest of the application.

When structured output is not enough

  • The model may still be wrong while perfectly formatted: valid JSON is not true JSON. Check important fields against other data.
  • Very large or deeply nested schemas hurt accuracy. Split into several smaller calls.
  • Models without native support fall back to tool calling or prompting; results vary, so test them.
  • Providers differ in which JSON Schema features they allow (for example some reject certain constraints). If you get a schema error, simplify.
flowchart LR
    S["Pydantic schema"] --> M["model.with_structured_output"]
    P["Prompt + text"] --> M
    M --> V["Validated object"]
    V --> A["Your application code"]

The schema is sent to the provider; the validated object comes back.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does model.with_structured_output(Movie) return?

    It wraps the model in a Runnable that sends the schema and returns validated objects.
  2. 2. Why write good Field(description=...) texts?

    Descriptions are part of the schema the model sees, so clear ones improve accuracy.
  3. 3. How do you stop a model from inventing a value for a field that may be absent?

    Optional fields let the model return None instead of making something up.
  4. 4. Valid structured output guarantees what?

    A schema guarantees shape, not truth, so verify critical values.

Summary

  • with_structured_output(schema) gives typed data directly, using the provider's native mechanism.
  • Prefer Pydantic models; docstrings and field descriptions guide the model.
  • Use Literal, enums and bounds to restrict values; validate anyway.
  • For extraction, use nested models, optional fields with None defaults and small schemas.
  • Structure guarantees format, not correctness.

Next: LCEL and the Pipe Operator