response_format contract for machine-readable output. In json_schema mode the engine uses grammar-constrained decoding: the sampler is restricted so the model can only emit tokens that keep the output valid against your schema — the response is guaranteed to parse and to conform. This is stronger than prompt-level “please answer in JSON” and stronger than post-hoc validation.
JSON Schema mode (recommended)
Setresponse_format.type to "json_schema" with a named schema and "strict": true:
message.content is a JSON string that always parses and always matches the schema:
JSON object mode
{"type": "json_object"} guarantees the output is some valid JSON object, without enforcing a particular shape. Use it when the structure is loose or evolving; prefer json_schema whenever you know the shape.
In
json_object mode, still tell the model in the prompt what keys you expect — the grammar guarantees valid JSON, not your field names.Schema tips
- Root must be an object — not an array, string, or number.
- Set
"additionalProperties": falseon every object so the model cannot invent extra keys. - Mark every property
required. For optional values, keep the key required and allow"type": ["string", "null"]instead — this is how OpenAI strict mode models optionality, and it keeps output shapes uniform. - Use
enumfor closed sets anddescriptionon properties to steer values; the constraint guarantees shape, your prompt and descriptions steer content. - Keep schemas as flat as practical — deeply nested or highly recursive schemas slow constrained decoding.
- Set
max_completion_tokensgenerously enough for the full object; if generation is cut off by the cap (finish_reason: "length"), the truncated string may not parse.
output_schema convenience field
As a non-standard convenience, BRAHMA also accepts a top-level output_schema field — a JSON Schema as a JSON-encoded string, applied the same way as response_format.json_schema.schema. It exists for callers that cannot easily nest the OpenAI response_format object. Prefer response_format for portability; when both carry a schema, the response_format schema wins.