Parameter Types in Structured Outputs (JSON)

This page provides usage examples of the JSON Schema parameters that are supported in Structured Outputs (JSON).

Note: Using Structured Outputs (JSON), the outputs are guaranteed to follow the schema for the tool name, parameter name, parameter data types, and the list of required parameters.

Basic types

String

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "title": {"type": "string"},
7            "author": {"type": "string"},
8        },
9        "required": ["title", "author"],
10    },
11}
12
13message = "Generate a JSON describing a book, with the fields 'title' and 'author'"

Example output:

1{
2    "title": "The Great Gatsby",
3    "author": "F. Scott Fitzgerald"
4}

Integer

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "title": {"type": "string"},
7            "author": {"type": "string"},
8            "publication_year": {"type": "integer"},
9        },
10        "required": ["title", "author", "publication_year"],
11    },
12}
13
14message = "Generate a JSON describing a book, with the fields 'title', 'author' and 'publication_year'"

Example output:

1{
2  "title": "The Great Gatsby",
3  "author": "F. Scott Fitzgerald",
4  "publication_year": 1925
5}

Float

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "city": {"type": "string"},
7            "temperature": {"type": "number"},
8        },
9        "required": ["city", "temperature"],
10    },
11}
12
13message = "Generate a JSON of a city and its average daily temperature in celcius"

Example output:

1{
2  "city": "Toronto",
3  "temperature": 15.6
4}

Boolean

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "city": {"type": "string"},
7            "is_capital": {"type": "boolean"},
8        },
9        "required": ["city", "is_capital"],
10    },
11}
12
13message = "Generate a JSON about a city in Spain and whether it is the capital of its country using 'is_capital'."

Example output:

1{
2    "city": "Madrid",
3    "is_capital": true
4}

Array

With specific types

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "cities": {
7                "type": "array",
8                "items": {"type": "string"},
9            }
10        },
11        "required": ["cities"],
12    },
13}
14
15message = "Generate a JSON listing three cities in Japan."

Example output:

1{
2  "cities": [
3    "Tokyo",
4    "Kyoto",
5    "Osaka"
6  ]
7}

Without specific types

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "cities": {
7                "type": "array",
8            }
9        },
10        "required": ["cities"],
11    },
12}
13
14message = "Generate a JSON listing three cities in Japan."

Example output:

1{
2  "cities": [
3    "Tokyo",
4    "Kyoto",
5    "Osaka"
6  ]
7}

Lists of lists

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "coordinates": {
7                "type": "array",
8                "items": {
9                    "type": "array",
10                    "items": {"type": "number"},
11                }
12            }
13        },
14        "required": ["coordinates"],
15    },
16}
17
18message = "Generate a JSON of three random coordinates."

Example output:

1{
2    "coordinates": [
3        [-31.28333, 146.41667],
4        [78.95833, 11.93333],
5        [44.41667, -75.68333]
6    ]
7}

Others

Nested objects

PYTHON
1response_format = {
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "actions": {
7                "type": "array",
8                "items": {
9                    "type": "object",
10                    "properties": {
11                        "japanese": {"type": "string"},
12                        "romaji": {"type": "string"},
13                        "english": {"type": "string"},
14                    },
15                    "required": ["japanese", "romaji", "english"],
16                },
17            }
18        },
19        "required": ["actions"],
20    },
21}
22
23message = "Generate a JSON array of 3 objects with the following fields: japanese, romaji, english. These actions should be japanese verbs provided in the dictionary form."

Example output:

1{
2    "actions": [
3        {
4            "japanese": "食べる",
5            "romaji": "taberu",
6            "english": "to eat"
7        },
8        {
9            "japanese": "話す",
10            "romaji": "hanasu",
11            "english": "to speak"
12        },
13        {
14            "japanese": "書く",
15            "romaji": "kaku",
16            "english": "to write"
17        }
18    ]
19}

Enums

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "genre": {"type": "string",
7                      "enum": ["historical fiction", "cozy mystery"]},
8            "title": {"type": "string"}
9        },
10        "required": ["title", "genre"],
11    },
12}
13
14message = "Generate a JSON for a new book idea."

Example output:

1{
2  "genre": "historical fiction",
3  "title": "The Unseen Thread: A Tale of the Silk Road's Secrets and Shadows"
4 }

Const

PYTHON
1response_format={
2    "type": "json_object", 
3    "schema": {
4        "type": "object",
5        "properties": {
6            "city": {
7                "type": "object",
8                "properties": {
9                    "country": {"type": "string", "const": "Thailand"},
10                    "city_name": {"type": "string"},
11                    "avg_temperature": {"type": "number"},
12                    
13                },
14                "required": ["country", "city_name", "avg_temperature"]
15            }
16        },
17        "required": ["city"],
18    },
19}
20
21message = "Generate a JSON of a city."

Example output:

1{
2  "city": {
3    "country": "Thailand",
4    "city_name": "Bangkok",
5    "avg_temperature": 29.083333333333332
6  }
7}

Pattern

PYTHON
1response_format={
2    "type": "json_object", 
3    "schema": {
4        "type": "object",
5        "properties": {
6            "product_sku": {
7                "type": "string",
8                "pattern": "[A-Z]{3}[0-9]{7}"
9            }
10        },
11        "required": ["product_sku"],
12    },
13}
14
15message = "Generate a JSON of an SKU for a new product line."

Example output:

1{
2  "product_sku": "PRX0012345"
3}

Format

PYTHON
1response_format={
2    "type": "json_object",
3    "schema": {
4        "type": "object",
5        "properties": {
6            "itinerary": {
7                "type": "array",
8                "items": {
9                    "type": "object",
10                    "properties": {
11                        "day_number": {"type": "integer"},
12                        "date": {"type": "string",
13                                 "format": "date"},
14                        "places_to_visit": {"type": "string"}
15                    },
16                    "required": ["day_number", "date", "places_to_visit"]
17                }
18            }
19        },
20        "required": ["itinerary"],
21    },
22}
23
24message = "Generate a JSON of a 3-day visit of Bali starting Jan 5 2025."

Example output:

1{
2  "itinerary": [
3    {
4      "day_number": 1,
5      "date": "2025-01-05",
6      "places_to_visit":  "Tanah Lot Temple, Ubud Monkey Forest, Tegalalang Rice Terraces"
7    },
8    {
9      "day_number": 2,
10      "date": "2025-01-06",
11      "places_to_visit": "Mount Batur, Tirta Empul Temple, Ubud Art Market"
12    },
13    {
14      "day_number": 3,
15      "date": "2025-01-07",
16      "places_to_visit": "Uluwatu Temple, Kuta Beach, Seminyak"
17    }
18  ]
19}