Posts Understanding Pydantic: Data Validation and Structured Outputs in Python
Post
Cancel

Understanding Pydantic: Data Validation and Structured Outputs in Python

Understanding Pydantic: Data Validation and Structured Outputs in Python

While building my RailOps AI Agent, a Python project that retrieves live UK railway information and recommends actions based on train delays and cancellations, I came across a Python library called Pydantic.

I had used it to define the format of responses generated by an LLM, but I wanted to understand what it was actually doing.

Why do we need Pydantic when Python already has dictionaries and classes? And how does it help when building AI applications?

1. What Is Pydantic?

Pydantic is a Python library for data validation and data modelling using Python type annotations.

It allows developers to define the structure and expected types of data and validate incoming values against those rules.

For example, suppose a train service has two attributes:

  • scheduled: the scheduled train time
  • status: whether the train is on time, delayed, cancelled, or unknown

A regular Python dictionary might look like this:

1
2
3
4
train = {
    "scheduled": "15:45",
    "status": "delayed"
}

However, a dictionary does not automatically enforce the types or permitted values of its contents.

This is also a valid Python dictionary:

1
2
3
4
train = {
    "scheduled": 1545,
    "status": "banana"
}

Syntactically, nothing is wrong. But the data is not valid for my application.

This is where Pydantic becomes useful.

2. Creating a Pydantic Model

Pydantic provides a class called BaseModel, which can be inherited to define a data model.

1
2
3
4
5
6
7
8
9
10
11
from pydantic import BaseModel
from typing import Literal

class TrainStatus(BaseModel):
    scheduled: str
    status: Literal[
        "on_time",
        "delayed",
        "cancelled",
        "unknown"
    ]

Let’s break this down.

BaseModel

This is the base class provided by Pydantic. By inheriting from it, TrainStatus gains automatic validation and serialisation capabilities.

scheduled: str

This indicates that scheduled is expected to be a string.

Literal[...]

This restricts the value of status to a predefined set of strings.

Now I can create an instance:

1
2
3
4
5
6
7
train = TrainStatus(
    scheduled="15:45",
    status="delayed"
)

print(train.status)
# delayed

If I provide an invalid status:

1
2
3
4
train = TrainStatus(
    scheduled="15:45",
    status="banana"
)

Pydantic raises a ValidationError because "banana" is not one of the permitted values.

One important detail is that Pydantic can coerce some input values into the expected types. If strict type checking is required, stricter validation can be configured.

3. What Happens When Validation Fails?

A Pydantic model validates its data when an instance is created.

For example:

1
2
3
4
5
6
7
8
9
from pydantic import ValidationError

try:
    train = TrainStatus(
        scheduled="15:45",
        status="banana"
    )
except ValidationError as error:
    print(error)

Instead of silently accepting invalid data, Pydantic reports which field failed validation and why.

This is particularly useful when working with external APIs, user inputs, or LLM-generated responses, where data may not always follow the expected structure.

4. Nested Pydantic Models

One of the most useful features of Pydantic is the ability to define models inside other models.

In my RailOps AI Agent, I defined two models:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class TrainStatus(BaseModel):
    scheduled: str
    status: Literal[
        "on_time",
        "delayed",
        "cancelled",
        "unknown"
    ]


class Decision(BaseModel):
    trains: list[TrainStatus]
    recommended_action: str
    reason: str

The TrainStatus model describes a single train.

The Decision model describes the complete response from the AI Agent.

In particular:

1
trains: list[TrainStatus]

means that the trains field must contain a list of objects that conform to the TrainStatus model.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
decision = Decision(
    trains=[
        TrainStatus(
            scheduled="15:45",
            status="delayed"
        ),
        TrainStatus(
            scheduled="16:00",
            status="on_time"
        )
    ],
    recommended_action="Consider the 16:00 train",
    reason="The earlier service is delayed."
)

This structure allows the application to handle multiple trains while keeping the data format consistent.

Pydantic also validates nested data, so invalid train statuses inside the list are rejected.

5. Using Pydantic with OpenAI Structured Outputs

This is where Pydantic became especially useful in my project.

Normally, an LLM might return an answer as natural language:

The 15:45 train is delayed. Consider taking the next available service.

This is readable for a person, but less convenient for an application that needs to process individual fields.

Instead, I wanted the LLM to return a structured response containing:

  • Train information
  • A recommended action
  • An explanation

Using the OpenAI Python SDK, I can provide a Pydantic model as the expected response format.

1
2
3
4
5
6
7
8
9
response = client.responses.parse(
    model="gpt-5.4-mini",
    input=(
        "The 15:45 train from Woking "
        "to London Waterloo is delayed. "
        "What should the passenger do?"
    ),
    text_format=Decision
)

The key parameter is:

1
text_format=Decision

This tells the SDK to use the Decision model as the structured response format.

The model’s schema is used to constrain the response structure, and the SDK parses the generated result into the corresponding Pydantic object.

I can then access the result:

1
2
3
4
5
6
7
8
decision = response.output_parsed

if decision is not None:
    print(decision.recommended_action)
    print(decision.reason)

    for train in decision.trains:
        print(train.scheduled, train.status)

Instead of manually extracting values from an unstructured paragraph, I can access attributes directly.

This makes the LLM’s output easier to integrate into application logic.

6. Tool Outputs vs. Structured Outputs

Another important distinction I learned while building RailOps is the difference between tool outputs and structured outputs.

My application uses Python functions to retrieve and process railway information.

For example, a tool might return:

1
2
3
4
5
6
{
    "scheduled": "15:45",
    "estimated": "15:52",
    "delay_minutes": 7.0,
    "status": "delayed"
}

This is the result of the application’s Python logic.

The LLM then receives this information and generates a response using the Decision schema.

These are two different stages:

Tool output: Data returned by a Python function or external service.

Structured output: The LLM’s final response, organised according to a predefined schema.

Pydantic validates the structure and permitted values of the final response.

However, there is an important limitation:

A structurally valid response is not necessarily a factually correct response.

For example, Pydantic can verify that status is "delayed", but it cannot automatically verify whether the train is actually delayed.

That requires comparison with the original railway data.

For this reason, deterministic calculations such as delay duration should remain in Python rather than relying on the LLM to calculate them.

7. Optional Values and More Detailed Models

As I expanded my RailOps project, I wanted to include more information about each train.

A more detailed model could look like this:

1
2
3
4
5
6
7
8
9
10
11
class TrainStatus(BaseModel):
    scheduled: str
    estimated: str
    platform: str | None
    delay_minutes: float | None
    status: Literal[
        "on_time",
        "delayed",
        "cancelled",
        "unknown"
    ]

Here:

1
delay_minutes: float | None

means the value can be either a floating-point number or None.

For example:

1
delay_minutes = 7.0

or:

1
delay_minutes = None

This is useful when the estimated time is unavailable or the API reports a non-numeric value such as "Delayed".

It is important to distinguish between a nullable field and a field that can be omitted.

In Pydantic v2:

1
delay_minutes: float | None

allows None, but the field is still required.

If I want to make the field optional when constructing the model, I can provide a default:

1
delay_minutes: float | None = None

8. Converting Pydantic Models to Dictionaries and JSON

Pydantic also makes it easy to serialise model instances.

For example:

1
2
3
4
5
6
7
train = TrainStatus(
    scheduled="15:45",
    estimated="15:52",
    platform="2",
    delay_minutes=7.0,
    status="delayed"
)

To convert it into a Python dictionary:

1
train.model_dump()

To convert it into a JSON string:

1
train.model_dump_json()

These features are useful when building APIs, storing structured results, or exchanging data between services.

9. Pydantic vs. Regular Python Classes

FeatureRegular Python ClassPydantic Model
Data structureDefined manuallyDefined using typed fields
Runtime validationUsually implemented manuallyBuilt in
Nested data validationManual implementationBuilt in
Dictionary conversionManual or custom logicmodel_dump()
JSON serialisationManual or custom logicmodel_dump_json()
Common use casesGeneral object-oriented programmingAPIs, configuration, structured data, LLM outputs

Pydantic is not an AI-specific library.

It is also widely used in backend development, particularly with frameworks such as FastAPI.

10. Key Takeaways

The main things I learned about Pydantic are:

  1. Pydantic defines and validates data structures using Python type annotations.
  2. BaseModel provides validation and serialisation functionality.
  3. Literal restricts values to a predefined set.
  4. Nested models allow complex responses to be organised into reusable components.
  5. OpenAI Structured Outputs can use Pydantic models to define the expected response format.
  6. Data validation does not guarantee factual accuracy. LLM outputs should still be checked against trusted source data when accuracy matters.

For my RailOps AI Agent, Pydantic provides a bridge between the flexibility of natural language generation and the predictable data structures required by software applications.

Understanding this distinction has helped me think more clearly about how to build reliable AI-powered systems.


Part of my learning journey in Python, software engineering, and Applied AI development.