How to intermediate · 3 min read

OpenAI structured outputs limitations

Quick answer

OpenAI structured_outputs have limitations including maximum token length constraints, inability to enforce complex nested schemas strictly, and occasional deviations from the requested format. The model may produce partial or malformed JSON if the prompt or schema is too complex or ambiguous.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

bash

pip install openai>=1.0

Step by step

Use the response_format parameter with the OpenAI chat.completions.create method to request structured JSON output. Note the token limits and schema simplicity to avoid errors.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name", "age"]
}

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Provide your name and age in JSON."}],
    response_format={"type": "json_schema", "json_schema": schema}
)

print(response.choices[0].message.content)

output

{
  "name": "Alice",
  "age": 30
}

Common variations

You can use different models like gpt-4.1 or gpt-4o-mini but be aware smaller models may produce less accurate structured outputs. Async calls and streaming are not supported with response_format. Complex nested schemas increase the chance of malformed output.

Troubleshooting

If the output is not valid JSON, simplify your schema or reduce prompt complexity.
Watch for token limit errors; keep your schema and prompt concise.
Use post-processing validation to handle partial or malformed outputs gracefully.

✅

Key Takeaways

OpenAI structured outputs require simple, flat JSON schemas for best reliability.
Token limits constrain the complexity and length of structured outputs.
Always validate and handle malformed or partial JSON in your integration.

Verified 2026-04 · gpt-4o, gpt-4.1, gpt-4o-mini

Verify ↗