Skip to main content
Structured outputs let you enforce machine-readable output instead of free-form text.

Endpoint support

Use structured outputs on:
  • /v1/chat/completions with response_format
  • /v1/responses with text.format
  • /v1/messages can still return JSON text, but does not use the same response_format contract

Request

Response

Contract notes

  • response_format.type should be text, json_object, or json_schema.
  • For json_schema, include a schema object (response_format.json_schema.schema on chat-style payloads, or text.format.schema on responses-style payloads).
  • Validate JSON on your server before downstream use.

Design your schema

Start with a small object, mark required fields explicitly, and use enums for known categories. Set additionalProperties: false when extra keys must be rejected. Keep the requested schema and your server validator in sync; version them together.

Validate the result

Parse and validate the complete result before using it downstream. This TypeScript example uses Zod and matches the weather schema above:
Handle refusals, missing content, and truncated responses before parsing. If validation fails, allow at most a bounded corrective retry, then return a safe failure. Retried generations can incur additional charges. Valid JSON does not establish that the values are factually correct or authorise an action. Track validation failures by model and schema version. Recheck your evaluation cases when either changes. For malformed JSON recovery, see response healing.
Last modified on October 18, 2026