Structured Outputs

Structured outputs let OpenAI models generate data in predefined schemas—such as JSON, CSV, or XML—making responses machine-readable, actionable, and easily integrated into applications, databases, or workflows. This article covers why structured outputs matter, their key benefits, common formats, and best practices for implementation.

Why Structured Outputs Matter

Structured outputs transform AI-generated text into formats that downstream systems can parse and process automatically. By specifying a consistent schema, you ensure responses are:

• Interpretable: Downstream services understand each field.
• Actionable: Applications can trigger workflows based on parsed values.
• Integrable: Easily imported into databases, APIs, or third-party tools.

Key Benefits of Structured Outputs

Example: Extracting Calendar Events

The following Python snippet uses Pydantic models with the OpenAI Python client to parse a chat completion into a structured CalendarEvent object:

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

event = completion.choices[0].message.parsed
print(event)

What Are Structured Output Formats?

Structured outputs follow a schema—such as JSON, CSV, or XML—so they can be consumed directly by applications, APIs, or databases, eliminating the need for complex post-processing.

JSON for API Integration

JSON is a lightweight, human-readable data format widely used in web APIs. It’s ideal for real-time data exchange between clients and servers.

In a real estate chatbot, when a user requests property details, the backend can return structured JSON. The chatbot then displays fields like address, price, and specifications:

Example JSON output for a property listing:

{
  "property_listings": {
    "address": "123 Main St Anytown, USA",
    "price": 350000,
    "number_of_bedrooms": 4,
    "number_of_bathrooms": 3
  }
}

CSV for Data Reports

CSV is the go-to format for tabular data and reports that can be imported into spreadsheets or data warehouses. It’s commonly used in financial reporting, inventory management, and sales analysis.

Example CSV output for a sales report:

product_name,units_sold,revenue
Smartphone,250,125000
Laptop,150,225000
Smartwatch,500,75000

Best Practices for Structured Outputs

1. Define the schema in your prompt.
   Clearly state “Output must be valid JSON” or “Return CSV rows only.”
2. Validate generated data.
   Use a JSON schema validator or CSV linter to catch format errors.
3. Fine-tune for consistency.
   For complex or domain-specific schemas, fine-tune the model on representative examples.

References

• OpenAI Python Library
• Pydantic Documentation
• JSON Schema Validation
• CSV Linter Tools