JSON mode or schema?
⚠️
Preview — this feature is being built; the design below is the spec.
response_format has two JSON settings:
| Setting | Guarantees | Use when |
|---|---|---|
{"type": "json_object"} | The reply is valid JSON. Keys and types are whatever the model chose. | Prototyping; the shape varies by input; you validate yourself. |
{"type": "json_schema", ...} with strict: true | Valid JSON with exactly the shape your schema describes. | Production; any code that reads specific fields. |
Why prefer a schema
- No silent drift. In JSON mode, a key can change from
orderNumbertoorder_numberbetween calls. A schema prevents that. - Shorter prompts. You no longer need paragraphs describing the format; the schema carries it.
- Fewer retries. Your own validation and retry loop goes away.
When JSON mode is the better fit
- The output is a free-form object whose keys come from the input, such as “extract every field you find on this form”. A schema with
additionalProperties: trueis possible, but JSON mode is simpler. - You are on a model that lacks
capabilities.json_schemabut hasjson_object(checkGET /v1/models).
Prompting in JSON mode
JSON mode requires the word “JSON” somewhere in your messages, so the model knows a JSON reply is expected; without it the request fails with 400 json_not_mentioned. Describe the keys you want and give one example object.
Was this page helpful?