Skip to main content
Add output_config.format to a run request and the run’s final answer is constrained to your JSON schema. The raw text returns in output; the parsed JSON returns in structured_output. Structured outputs run in strict mode. Strict mode has three rules beyond ordinary JSON Schema:
  • The root schema must have "type": "object".
  • Every object must set "additionalProperties": false.
  • Every object must list ALL of its properties keys in required. Mark a field optional with a ["<type>", "null"] type union instead.
The configuration must also meet these rules:
  • format.type must be "json_schema".
  • minItems can only be 0 or 1.
  • Schemas are limited to 64 levels of nesting, 5,000 values, and 1,000 keys or items per object or array.
A configuration that breaks a rule returns 400 with the code invalid_output_config and a message that names the problem and, where one applies, the path.
structured_output is null until the run completes. A run that ends as failed or cancelled returns structured_output: null, even when output has text. A completed run also returns null when its final text is missing or is not a JSON object, for example after a refusal. The agent can still use tools during a structured-output run; the schema constrains the final answer only.