Skip to main content
Structured outputs let you ask models for machine-readable results instead of unconstrained prose.

​
JSON Prompting vs Schema Enforcement

Prompting for JSON only asks the model to behave. Schema enforcement gives the model an explicit shape to follow. Use schema enforcement when your application depends on:
  • required keys always being present
  • enums staying valid
  • arrays and nested objects staying well-formed
  • downstream parsers not breaking on malformed text

​
Support Matrix

APIMain request fieldNotes
Responsestext.formatBest starting point for new structured-output work
Chat Completionsresponse_formatUse when you need OpenAI chat compatibility
MessagesNo generic structured-output fieldUse tool schemas for Anthropic-style tool workflows when needed

​
When To Use It

  • extract entities, events, or records into a fixed schema
  • feed model output into downstream automation
  • reduce parser failures caused by malformed JSON
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1",
    input="Extract the event details from: Alice and Bob are going to a science fair on Friday.",
    text={
        "format": {
            "type": "json_schema",
            "name": "calendar_event",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "date": {"type": "string"},
                    "participants": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                },
                "required": ["name", "date", "participants"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    },
)

print(response.output_text)
Raw HTTP responses still carry the structured result as JSON text inside the normal output content. Exact wire examples live in the API-specific guides.

​
API-Specific Guides

​
Pitfalls

  • JSON prompting is weaker than schema enforcement
  • strict: true helps, but your schema still needs required fields and closed objects where that matters