Structured Outputs & JSON Mode

Type-Safe AI Outputs

When building applications, you need the AI to return data in a predictable format. OpenAI provides two mechanisms:

JSON Mode (Basic)

Setting response_format: { type: "json_object" } guarantees valid JSON output. You must still instruct the model about the schema in your prompt.

Structured Outputs (Strict — Recommended)

Introduced in late 2024, Structured Outputs mathematically constrains the model to only produce tokens valid under your JSON Schema. Uses a Context-Free Grammar (CFG) engine at the token generation level.

const response = await openai.responses.create({
  model: "gpt-5.4",
  input: "Extract: John Doe, age 30, works at Acme Corp",
  text: {
    format: {
      type: "json_schema",
      name: "user_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "number" },
          company: { type: "string" }
        },
        required: ["name", "age", "company"],
        additionalProperties: false
      }
    }
  }
});

When to Use Each