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.

Helper code

The examples on this page each provide a response_format schema and a message (the user message). To get an output, pass those values to a Chat endpoint call, as shown in the helper code below.

PYTHON

1 import cohere
2 
3 co = cohere.ClientV2(api_key="YOUR API KEY")
4 
5 res = co.chat(
6     # The model name. Example: command-a-plus-05-2026
7     model="MODEL_NAME",
8     # The user message. Optional - you can first add a `system_message` role
9     messages=[
10         {
11             "role": "user",
12             "content": message,
13         }
14     ],
15     # The schema that you define
16     response_format=response_format,
17     # Typically, you'll need a low temperature for more deterministic outputs
18     temperature=0,
19 )
20 
21 print(res.message.content[0].text)

Basic types

String

PYTHON

1 response_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 
13 message = "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

1 response_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 
14 message = "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

1 response_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 
13 message = "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

1 response_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 
13 message = "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

1 response_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 
15 message = "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

1 response_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 
14 message = "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

1 response_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 
18 message = "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

1 response_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 
23 message = "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

1 response_format = {
2     "type": "json_object",
3     "schema": {
4         "type": "object",
5         "properties": {
6             "genre": {
7                 "type": "string",
8                 "enum": ["historical fiction", "cozy mystery"],
9             },
10             "title": {"type": "string"},
11         },
12         "required": ["title", "genre"],
13     },
14 }
15 
16 message = "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

1 response_format = {
2     "type": "json_object",
3     "schema": {
4         "type": "object",
5         "properties": {
6             "city": {
7                 "type": "object",
8                 "properties": {
9                     "country": {
10                         "type": "string",
11                         "const": "Thailand",
12                     },
13                     "city_name": {"type": "string"},
14                     "avg_temperature": {"type": "number"},
15                 },
16                 "required": [
17                     "country",
18                     "city_name",
19                     "avg_temperature",
20                 ],
21             }
22         },
23         "required": ["city"],
24     },
25 }
26 
27 message = "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

1 response_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 
15 message = "Generate a JSON of an SKU for a new product line."

Example output:

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

Format

PYTHON

1 response_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", "format": "date"},
13                         "places_to_visit": {"type": "string"},
14                     },
15                     "required": [
16                         "day_number",
17                         "date",
18                         "places_to_visit",
19                     ],
20                 },
21             }
22         },
23         "required": ["itinerary"],
24     },
25 }
26 
27 message = (
28     "Generate a JSON of a 3-day visit of Bali starting Jan 5 2025."
29 )

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 }

1	import cohere
2
3	co = cohere.ClientV2(api_key="YOUR API KEY")
4
5	res = co.chat(
6	# The model name. Example: command-a-plus-05-2026
7	model="MODEL_NAME",
8	# The user message. Optional - you can first add a `system_message` role
9	messages=[
10	{
11	"role": "user",
12	"content": message,
13	}
14	],
15	# The schema that you define
16	response_format=response_format,
17	# Typically, you'll need a low temperature for more deterministic outputs
18	temperature=0,
19	)
20
21	print(res.message.content[0].text)

1	response_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
13	message = "Generate a JSON describing a book, with the fields 'title' and 'author'"

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

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

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

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	}

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

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

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	}