Skip to main content
Use text.format when your application needs schema-shaped output instead of free-form prose. On the wire, the structured result still comes back as JSON text inside a normal message item. Choose this when downstream code depends on a predictable schema, not just “please answer in JSON” prompting.

​
Request

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 an event from: Alice and Bob are going to a science fair on Friday.",
    text={
        "format": {
            "type": "json_schema",
            "name": "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)

​
Response Shape

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "{\"name\":\"Science Fair\",\"date\":\"Friday\",\"participants\":[\"Alice\",\"Bob\"]}",
      "annotations": [],
      "logprobs": []
    }
  ]
}

​
Choose the right mode

ModeUse it when
json_schemayou need required fields, enums, nested objects, or strict validation
json_objectyou only need valid JSON without full schema enforcement

​
How To Read The Result

  • parse the JSON string from output[*].content[*].text
  • if you only need valid JSON and not schema enforcement, use text.format.type: "json_object" instead

​
Caveats

  • strict: true works best with a closed schema such as additionalProperties: false
  • the wire response remains item-based even when the output is structured
  • model support still depends on the selected model

​
Common mistakes

  • expecting a native JSON object instead of parsing the returned text
  • using an open schema when the app really needs closed, validated output
  • assuming every model supports strict schema following equally well