How to structure JSON in LLMs with Pydantic for APIs

The challenge of obtaining structured data from language models

When interacting with an artificial intelligence model, the output is typically free-form text in a narrative format. In real-world software applications, however, we need this data organized into rigid structures, like a JSON object, to be consumed by databases and APIs. In practice, this means that if the artificial intelligence forgets a comma or invents a different key, the entire system workflow can break due to a parsing error.

To solve this problem, major language model platforms introduced function calling capabilities. This mechanism instructs the model to ignore prose and fill in the fields of a predefined schema. However, relying solely on the model's good behavior is rarely enough in critical environments, since subtle variations in text can still slip past basic format checks. This is precisely where data validation engineering at the code level comes into play.

Before moving forward with implementation, it is worth noting that structuring data securely shares similarities with the techniques discussed in our guide on securing AI agents with guardrails, where the primary objective is to impose strict limits on model behavior. Without these containment barriers, building complex automated workflows becomes a risky bet. Let's look at how to shield this communication using one of the most popular tools in the Python ecosystem.

The role of Pydantic in schema validation

Pydantic is a library focused on data validation and settings management in Python that utilizes native language type hints. In practice, it acts as a strict auditor on the input of any information, immediately rejecting any data that violates established rules. When we combine this tool with language models, we create an unnegotiable contract between the artificial intelligence and our backend.

Defining a structure with Pydantic is simple and straightforward, requiring only that you declare a class inheriting from BaseModel and specify the expected types for each field. If the language model attempts to return a string where an integer should exist, Pydantic intercepts the error before it reaches the database and flags exactly where the structure failed. This approach drastically reduces the amount of exception handling code you would otherwise need to scatter across the system.

Furthermore, this clarity in data modeling facilitates integration with other components of the artificial intelligence ecosystem, such as complex subagent architecture with LangGraph, where multiple software blocks exchange structured information constantly. Maintaining a rigid communication standard prevents one agent from misinterpreting the result generated by another.

Implementing Function Calling with strict validation

To get our hands dirty, let's create a practical data extraction example where the artificial intelligence must read unstructured text and transform it into a validated object. First, we define the expected data structure using Pydantic classes with their respective types and detailed descriptions to guide the model.

The descriptions inserted into the fields serve as vital contextual hints for the model to understand exactly what type of information to fill in each attribute. Below is a functional example of how to configure this structure in a modern Python project:

from pydantic import BaseModel, Field

class ExtractedUser(BaseModel):
    name: str = Field(description='Full name of the customer')
    age: int = Field(description='Age in complete years')
    active: bool = Field(description='User account status')

# Example of simulated usage with defined schema
schema_json = ExtractedUser.model_json_schema()
print(schema_json)

This schema generated in JSON format is sent directly to the language model API during the request. When the model processes the input, it is forced to map the response to the exact keys defined in the code, ensuring interoperability with the rest of the application.

Handling failures and ensuring production resilience

Even with well-defined schemas and clear instructions, unstable networks and models under high load can occasionally return truncated or incomplete responses. Therefore, robust production engineering requires your code to be prepared to capture validation failures and retry in a controlled manner. Using try-except blocks alongside Pydantic's specific exceptions is essential to prevent abrupt crashes.

Another recommended best practice is implementing self-correction mechanisms, where the error message generated by Pydantic is fed back to the artificial intelligence in the next turn, instructing it to fix the faulty field. This technique considerably raises the success rate in complex data extraction, turning a processing error into an opportunity for automatic adjustment. To explore these architectural concepts further in production, see our related technical analysis on Gemini on Apple CarPlay: How to use Google's AI in car.

Final considerations

Ensuring that artificial intelligence responses return consistent data structures is no longer a luxury but a basic requirement for production systems. By uniting the generation power of language models with Pydantic's validation rigor, we build reliable bridges between free-form text and corporate APIs. This engineering discipline not only saves development time but also elevates the reliability of all automated infrastructure you decide to deploy.