How to beginner · 3 min read

How to define JSON schema for OpenAI structured outputs

Q: How to define JSON schema for OpenAI structured outputs

Use the functions parameter in the OpenAI chat completions API to define a JSON schema for structured outputs. Specify the schema with type, properties, and required fields to enforce the output format, enabling the model to return JSON-conformant data.

Quick answer

Use the functions parameter in the OpenAI chat completions API to define a JSON schema for structured outputs. Specify the schema with type, properties, and required fields to enforce the output format, enabling the model to return JSON-conformant data.

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

Define a JSON schema in the functions parameter of the chat.completions.create call to instruct the model to output structured JSON data. The schema uses standard JSON Schema syntax with type, properties, and required fields.

python

import os
from openai import OpenAI

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

functions = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Name of the city"},
                "temperature": {"type": "number", "description": "Temperature in Celsius"},
                "condition": {"type": "string", "description": "Weather condition description"}
            },
            "required": ["city", "temperature", "condition"]
        }
    }
]

messages = [
    {"role": "user", "content": "What's the weather like in New York?"}
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    functions=functions,
    function_call={"name": "get_weather"}  # force function call
)

json_output = response.choices[0].message.function_call.arguments
print("Structured JSON output:", json_output)

output

Structured JSON output: {"city": "New York", "temperature": 18.5, "condition": "Partly cloudy"}

Common variations

Use function_call="auto" to let the model decide when to return structured data.
Define multiple functions with different schemas for varied structured outputs.
Use async calls with asyncio and the OpenAI SDK for concurrency.
Switch models like gpt-4o-mini for faster, cheaper responses.

Troubleshooting

If the model returns unstructured text, ensure functions and function_call parameters are correctly set.
Validate your JSON schema syntax to avoid errors.
Check API key and environment variables if authentication fails.
Use print(response) to debug raw API responses.

✅

Key Takeaways

Use the OpenAI functions parameter to define JSON schemas for structured outputs.
Specify type, properties, and required fields to enforce output format.
Force or auto-enable function calls to get consistent JSON responses from the model.
Validate your schema and API parameters to avoid unstructured or invalid outputs.

Verified 2026-04 · gpt-4o-mini

Verify ↗