Structured Outputs - OpenML's AI Blogs

JSON is one of the most widely used formats in the world for applications to exchange data. Structured Outputs is a feature that ensures the model will always generate responses that adhere to our supplied JSON Schema, so we don’t need to worry about the model omitting a required key, or hallucinating an invalid enum value.

Why Use Structured Outputs#

Without structured outputs, LLM can generate malformed JSON responses or invalid tool inputs that break our applications. Even with careful prompting, we may encounter:

Parsing errors from invalid JSON syntax
Missing required fields
Inconsistent data types
Schema violations requiring error handling and retries

Structured outputs guarantee schema-compliant responses through constrained decoding:

Reliable type-safety: No need to validate or retry incorrectly formatted responses
Explicit refusals: Safety-based model refusals are now programmatically detectable
Simpler prompting: No need for strongly worded prompts to achieve consistent formatting

Quick Start#

Claude - JSON outputs#

JSON outputs control Claude’s response format, ensuring Claude returns valid JSON matching our schema. Use JSON outputs when we need to:

Control Claude’s response format
Extract data from images or text
Generate structured reports
Format API responses

1
client = anthropic.Anthropic()
2

3
response = client.messages.create(
4
    model="claude-opus-5",
5
    max_tokens=1024,
6
    messages=[
7
        {
8
            "role": "user",
9
            "content": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
10
        }
11
    ],
12
    output_config={
13
        "format": {
14
            "type": "json_schema",
15
            "schema": {
16
                "type": "object",
17
                "properties": {
18
                    "name": {"type": "string"},
19
                    "email": {"type": "string"},
20
                    "plan_interest": {"type": "string"},
21
                    "demo_requested": {"type": "boolean"},
22
                },
23
                "required": ["name", "email", "plan_interest", "demo_requested"],
24
                "additionalProperties": False,
25
            },
26
        }
27
    },
28
)
29
print(next(block.text for block in response.content if block.type == "text"))

Response format: Valid JSON matching our schema in the response’s text content block

1
{
2
  "name": "John Smith",
3
  "email": "john@example.com",
4
  "plan_interest": "Enterprise",
5
  "demo_requested": true
6
}

How it works

Define our JSON schema: Create a JSON schema that describes the structure we want Claude to follow. The schema uses standard JSON Schema format with some limitations (see JSON Schema limitations).

Add the output_config.format parameter: Include the output_config.format parameter in our API request with type: "json_schema" and our schema definition.

Parse the response: Claude’s response is valid JSON matching our schema, returned in the response’s text content block.

OpenAI#

1
response = client.responses.create(
2
    model="gpt-6-astra",
3
    input=[
4
        {
5
            "role": "system",
6
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
7
        },
8
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
9
    ],
10
    text={
11
        "format": {
12
            "type": "json_schema",
13
            "name": "math_response",
14
            "schema": {
15
                "type": "object",
16
                "properties": {
17
                    "steps": {
18
                        "type": "array",
19
                        "items": {
20
                            "type": "object",
21
                            "properties": {
22
                                "explanation": {"type": "string"},
23
                                "output": {"type": "string"},
24
                            },
25
                            "required": ["explanation", "output"],
26
                            "additionalProperties": False,
27
                        },
28
                    },
29
                    "final_answer": {"type": "string"},
30
                },
31
                "required": ["steps", "final_answer"],
32
                "additionalProperties": False,
33
            },
34
            "strict": True,
35
        },
36
    },
37
)
38

39
print(response.output_text)

NOTE
The first request we make with any schema will have additional latency as our API processes the schema, but subsequent requests with the same schema will not have additional latency.

How it works
Define our schema: First you must design the JSON Schema that the model should be constrained to follow. While Structured Outputs supports much of JSON Schema, some features are unavailable either for performance or technical reasons. See here for more details.
Supply schema in the API call: To use Structured Outputs, simply specify
1
text: { format: { type: "json_schema", "strict": true, "schema": … } }
Handle edge cases: In some cases, the model might not generate a valid response that matches the provided JSON schema. This can happen in the case of a refusal, if the model refuses to answer for safety reasons, or if for example we reach a max tokens limit and the response is incomplete.

Working with JSON Outputs in SDKs#

In addition to supporting JSON Schema in the REST API, the SDKs of OpenAI, Claude, Gemini for Python and JavaScript also make it easy to define object schemas using Pydantic and Zod respectively.

The SDKs provide helpers that make it easier to work with JSON outputs, including schema transformation, automatic validation, and integration with popular schema libraries.

We can see how to extract information from unstructured text that conforms to a schema defined in vendor-specific sections below.

Claude#

1
from pydantic import BaseModel
2
from anthropic import Anthropic
3

4

5
class ContactInfo(BaseModel):
6
    name: str
7
    email: str
8
    plan_interest: str
9
    demo_requested: bool
10

11

12
client = Anthropic()
13

14
response = client.messages.parse(
15
    model="claude-opus-5",
16
    max_tokens=1024,
17
    messages=[
18
        {
19
            "role": "user",
20
            "content": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
21
        }
22
    ],
23
    output_format=ContactInfo,
24
)
25

26
print(response.parsed_output)

OpenAI#

1
from openai import OpenAI
2
from pydantic import BaseModel
3

4
client = OpenAI()
5

6

7
class CalendarEvent(BaseModel):
8
    name: str
9
    date: str
10
    participants: list[str]
11

12

13
response = client.responses.parse(
14
    model="gpt-6-astra",
15
    input=[
16
        {"role": "system", "content": "Extract the event information."},
17
        {
18
            "role": "user",
19
            "content": "Alice and Bob are going to a science fair on Friday.",
20
        },
21
    ],
22
    text_format=CalendarEvent,
23
)
24

25
event = response.output_parsed

Gemini#

This example demonstrates how to extract structured data from text using basic JSON Schema types like object, array, string, and integer.

1
from google import genai
2
from pydantic import BaseModel, Field
3
from typing import List, Optional
4

5
class Ingredient(BaseModel):
6
    name: str = Field(description="Name of the ingredient.")
7
    quantity: str = Field(description="Quantity of the ingredient, including units.")
8

9
class Recipe(BaseModel):
10
    recipe_name: str = Field(description="The name of the recipe.")
11
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
12
    ingredients: List[Ingredient]
13
    instructions: List[str]
14

15
client = genai.Client()
16

17
prompt = """
18
Please extract the recipe from the following text.
19
The user wants to make delicious chocolate chip cookies.
20
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
21
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
22
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
23
For the best part, they'll need 2 cups of semisweet chocolate chips.
24
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
25
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
26
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
27
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
28
onto ungreased baking sheets and bake for 9 to 11 minutes.
29
"""
30

31
interaction = client.interactions.create(
32
    model="gemini-3.8-flash",
33
    input=prompt,
34
    response_format={
35
        "type": "text",
36
        "mime_type": "application/json",
37
        "schema": Recipe.model_json_schema()
38
    },
39
)
40

41
recipe = Recipe.model_validate_json(interaction.output_text)
42
print(recipe)

Resources#

Direct links to the official documentation for structured outputs across the major API providers: