Achieve Perfect JSON Formatting with OpenAI API's Structured Outputs

Any developer that has worked with OpenAI API responses and tried to get the response formatted as JSON knows how annoying it is.

It is unreliable at the least, and the way you’d get around this is by putting the response through a JSON parser or calling OpenAI API a second time to restructure the response into valid JSON format.

But no more… Structured Outputs from OpenAI saves the day. It guarantees that the response you get back is JSON and formatted according to the JSON schema that you provide it.

The documentation is outdated since it doesn’t include how the Responses API is supported, but I got you.

I will show you how to use Structured Outputs with Python, OpenAI SDK with Response API and pydantic.

Step 1 - Define your schema

from pydantic import BaseModel
from openai import OpenAI

class Step(BaseModel):
    explanation: str
    output: str

class MathResponse(BaseModel):
    steps: list[Step]
    final_answer: str

Step 2 - Pass in the schema to API call

from pydantic import BaseModel
from openai import OpenAI

class Step(BaseModel):
    explanation: str
    output: str

class MathResponse(BaseModel):
    steps: list[Step]
    final_answer: str

client = OpenAI()

response = client.responses.create(
                model="gpt-4o-2024-08-06",
                input = [
                    {
                        "role": "system",
                        "content": "You are a helpful math tutor."
                    },
                    {
                        "role": "user",
                        "content": "solve 8x + 31 = 2"
                    }
                ],
                text={
                    "format": {
                        "type": "json_schema",
                        "name": "math_response",
                        "schema": MathResponse.model_json_schema()
                    }
                }              
            )

And that’s it, you will get perfectly formatted JSON response from the model, every time without the hassle.