How to intermediate · 3 min read

How to validate OpenAI JSON response in python

Q: How to validate OpenAI JSON response in python

Use Python's jsonschema library to validate the structure of OpenAI JSON responses against a defined schema. Additionally, check for required fields like choices and handle exceptions to ensure the response is valid and complete.

Quick answer

Use Python's jsonschema library to validate the structure of OpenAI JSON responses against a defined schema. Additionally, check for required fields like choices and handle exceptions to ensure the response is valid and complete.

PREREQUISITES

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

Setup

Install the required packages and set your OpenAI API key as an environment variable.

Install OpenAI SDK and jsonschema: pip install openai jsonschema
Set environment variable in your shell: export OPENAI_API_KEY='your_api_key'

bash

pip install openai jsonschema

Step by step

Use the OpenAI SDK to call the API, then validate the JSON response using jsonschema. This example checks for the presence and type of key fields.

python

import os
from openai import OpenAI
import jsonschema

# Define the expected JSON schema for the response
response_schema = {
    "type": "object",
    "properties": {
        "id": {"type": "string"},
        "object": {"type": "string"},
        "created": {"type": "integer"},
        "model": {"type": "string"},
        "choices": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "index": {"type": "integer"},
                    "message": {
                        "type": "object",
                        "properties": {
                            "role": {"type": "string"},
                            "content": {"type": "string"}
                        },
                        "required": ["role", "content"]
                    },
                    "finish_reason": {"type": ["string", "null"]}
                },
                "required": ["index", "message", "finish_reason"]
            },
            "minItems": 1
        },
        "usage": {
            "type": "object",
            "properties": {
                "prompt_tokens": {"type": "integer"},
                "completion_tokens": {"type": "integer"},
                "total_tokens": {"type": "integer"}
            },
            "required": ["prompt_tokens", "completion_tokens", "total_tokens"]
        }
    },
    "required": ["id", "object", "created", "model", "choices", "usage"]
}

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

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Say hello"}]
    )
    # Validate the JSON response against the schema
    jsonschema.validate(instance=response, schema=response_schema)
    print("Response is valid JSON and matches schema.")
    print("Generated text:", response.choices[0].message.content)
except jsonschema.ValidationError as e:
    print("JSON schema validation error:", e.message)
except Exception as e:
    print("Error calling OpenAI API or processing response:", str(e))

output

Response is valid JSON and matches schema.
Generated text: Hello

Common variations

You can validate asynchronously using asyncio with the OpenAI SDK's async client. Also, adapt the schema for different models or endpoints by adjusting expected fields.

python

import asyncio
import os
from openai import OpenAI
import jsonschema

response_schema = { /* same schema as above */ }

async def validate_async():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    response = await client.chat.completions.acreate(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello async"}]
    )
    jsonschema.validate(instance=response, schema=response_schema)
    print("Async response valid:", response.choices[0].message.content)

asyncio.run(validate_async())

output

Async response valid: Hello async

Troubleshooting

If you get a ValidationError, check your schema matches the API response structure.
If the API call fails, verify your API key and network connectivity.
Use print(response) to inspect raw JSON for unexpected changes.

✅

Key Takeaways

Use jsonschema to enforce expected JSON structure from OpenAI responses.
Always handle exceptions to catch API errors and validation failures.
Adjust your schema when switching models or API versions to avoid validation errors.

Verified 2026-04 · gpt-4o

Verify ↗