OpenAI Structured Outputs: Enforce JSON Schema (2026)

The OpenAI API’s structured output feature is less about enforcing a schema and more about guiding the model to produce output that conforms to a schema.

Let’s see this in action. Imagine you want to extract structured data about products from text. We’ll use the openai Python library.

import openai
import json

# Assume you have your API key set as an environment variable
# openai.api_key = "YOUR_API_KEY"

def extract_product_info(text):
    response = openai.chat.completions.create(
        model="gpt-4o",
        response_format={ "type": "json_object" },
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant designed to output JSON. You will be provided with text, and you need to extract product information in the specified JSON format."
            },
            {
                "role": "user",
                "content": f"""
                Extract the product name, price, and available colors from the following text:
                "{text}"
                """
            }
        ],
        temperature=0.0, # Set to 0 for deterministic output
        max_tokens=150
    )
    return response.choices[0].message.content

# Define the JSON schema implicitly through the prompt and response_format
# The model will try to adhere to this structure.
# In a real-world scenario, you'd likely have a formal JSON schema object.

sample_text_1 = "Check out the new SuperWidget X, it's only $99.99 and comes in red, blue, and green."
sample_text_2 = "We have the GadgetPro 2000 on sale for $149.00. It's available in black and silver."
sample_text_3 = "The amazing Thingamajig is priced at $75.00. You can get it in yellow."

# Example of how to call the function and parse the output
try:
    product_data_1 = json.loads(extract_product_info(sample_text_1))
    print("Product 1:", json.dumps(product_data_1, indent=2))

    product_data_2 = json.loads(extract_product_info(sample_text_2))
    print("Product 2:", json.dumps(product_data_2, indent=2))

    product_data_3 = json.loads(extract_product_info(sample_text_3))
    print("Product 3:", json.dumps(product_data_3, indent=2))

except json.JSONDecodeError as e:
    print(f"JSON Decode Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

The core idea behind structured outputs is to leverage the LLM’s ability to understand and generate text that adheres to a predefined format. By setting response_format={ "type": "json_object" } and guiding the model with a system prompt that describes the desired JSON structure, you’re essentially creating a contract. The model attempts to fulfill this contract by generating JSON.

Here’s how it breaks down internally:

1. Model Training: Models like gpt-4o are trained on vast amounts of text, including code and structured data. They learn patterns of language and how to represent information in various formats, including JSON.
2. Prompt Engineering: The system prompt and the user prompt work in tandem. The system prompt sets the persona and the output constraint (JSON object). The user prompt provides the specific task and the data to be processed, implicitly defining the fields expected within the JSON. For instance, asking to extract "product name, price, and available colors" directly informs the model about the keys it should aim for in its JSON output.
3. response_format Parameter: This is the critical enabler. When set to "json_object", it tells the OpenAI API to instruct the model to only output valid JSON. The API will then post-process the model’s raw output to ensure it’s valid JSON before returning it. If the model fails to produce valid JSON, the API might retry or return an error, depending on the exact implementation details and model capabilities.
4. temperature Parameter: Setting temperature to 0.0 is crucial for predictable, deterministic output. Higher temperatures introduce randomness, which is antithetical to generating consistent, schema-compliant JSON.

The system doesn’t literally enforce a JSON Schema in the way a traditional compiler or validator would. Instead, it guides the model to produce output that conforms to an implied schema. The response_format parameter is the primary mechanism. If the model deviates significantly or produces invalid JSON, the API might return an error, effectively rejecting the output.

When you’re debugging or optimizing these structured outputs, remember that the model is still a language model. It doesn’t "understand" JSON Schema validation in the same way a program does. It’s pattern matching and generating text that looks like valid JSON based on its training. The response_format parameter is a strong directive, but edge cases can still occur.

The most surprising thing about this feature is how robust it is, even when the instructions are only implicitly defined by the prompt. The gpt-4o model, in particular, is remarkably good at inferring the structure and data types required for the JSON output based on natural language requests. You can often achieve reliable structured output without explicitly providing a formal JSON schema definition to the API itself, relying solely on the prompt to describe the desired output shape.

The next step is often handling potential data type mismatches or missing fields within the generated JSON, which requires careful parsing and validation logic on your end.