Guides
Structured output
Constrain model output with response_format, and how to recover when parsing fails.
When you need machine-readable output, constrain the format with response_format instead of writing
"output only JSON" in the prompt.
JSON object mode
resp = client.chat.completions.create(
model="gpt-5.4-mini",
messages=[{"role": "user", "content": "Extract 'Jane, 28, Berlin' as JSON"}],
response_format={"type": "json_object"},
)
print(resp.choices[0].message.content) # {"name":"Jane","age":28,"city":"Berlin"}json_object wants the word JSON in the prompt
The OpenAI protocol requires the prompt to mention "JSON" in json_object mode; otherwise some models
error out. JSON Schema mode is the sturdier option.
JSON Schema mode
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"city": {"type": "string"},
},
"required": ["name", "age", "city"],
"additionalProperties": False,
}
resp = client.chat.completions.create(
model="gpt-5.4-mini",
messages=[{"role": "user", "content": "Extract 'Jane, 28, Berlin' as structured data"}],
response_format={"type": "json_schema", "json_schema": {"name": "person", "schema": schema, "strict": True}},
)When parsing fails
Keep a fallback even with a schema:
- Try
json.loads; on failure, send the raw text plus the error back and ask the model to fix the format only - If that fails again, degrade to "return raw text and ask a human"
- Never silently drop an unparseable response — users read it as "the model said nothing"
Support varies by model
- Models with strict
json_schemahonour types and required fields most reliably - Models with only
json_objectmay still deviate in field names or types - Models with no
response_formatsupport can only be constrained by prompt, so the fallback above matters
See Models.