Structured outputs make a model follow a JSON Schema definition that you provide as part of your inference API call. This approach contrasts with the older JSON mode feature, which guaranteed valid JSON but couldn’t ensure strict adherence to the supplied schema. Use structured outputs for function calling, extracting structured data, and building complex multi-step workflows.
JSON Schema support and limitations
Azure OpenAI structured outputs support the same subset of the JSON Schema as OpenAI.
Supported types
- String
- Number
- Boolean
- Integer
- Object
- Array
- Enum
- anyOf
Root objects can’t be the anyOf type.
All fields must be required
Include all fields or function parameters as required. In the following example, both location and unit appear under "required": ["location", "unit"].
{
"name": "get_weather",
"description": "Fetches the weather in the given location",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The location to get the weather for"
},
"unit": {
"type": "string",
"description": "The unit to return the temperature in",
"enum": ["F", "C"]
}
},
"additionalProperties": false,
"required": ["location", "unit"]
}
}
null. In this example, this approach is represented by the line "type": ["string", "null"],.
{
"name": "get_weather",
"description": "Fetches the weather in the given location",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The location to get the weather for"
},
"unit": {
"type": ["string", "null"],
"description": "The unit to return the temperature in",
"enum": ["F", "C"]
}
},
"additionalProperties": false,
"required": [
"location", "unit"
]
}
}
Nesting depth
A schema can have up to 100 object properties total, with up to five levels of nesting.
Always set additionalProperties: false in objects
This property controls if an object can have other key value pairs that weren’t defined in the JSON Schema. To use structured outputs, set this value to false.
Key ordering
Structured outputs follow the same order as the provided schema. To change the output order, modify the order of the schema that you send as part of your inference request.
Unsupported type-specific keywords
| Type | Unsupported Keyword |
|---|
| String | minlength
maxLength
pattern
format |
| Number | minimum
maximum
multipleOf |
| Objects | patternProperties
unevaluatedProperties
propertyNames
minProperties
maxProperties |
| Arrays | unevaluatedItems
contains
minContains
maxContains
minItems
maxItems
uniqueItems |
Nested schemas using anyOf must adhere to the overall JSON Schema subset
Example supported anyOf schema:
{
"type": "object",
"properties": {
"item": {
"anyOf": [
{
"type": "object",
"description": "The user object to insert into the database",
"properties": {
"name": {
"type": "string",
"description": "The name of the user"
},
"age": {
"type": "number",
"description": "The age of the user"
}
},
"additionalProperties": false,
"required": [
"name",
"age"
]
},
{
"type": "object",
"description": "The address object to insert into the database",
"properties": {
"number": {
"type": "string",
"description": "The number of the address. Eg. for 123 main st, this would be 123"
},
"street": {
"type": "string",
"description": "The street name. Eg. for 123 main st, this would be main st"
},
"city": {
"type": "string",
"description": "The city of the address"
}
},
"additionalProperties": false,
"required": [
"number",
"street",
"city"
]
}
]
}
},
"additionalProperties": false,
"required": [
"item"
]
}
Definitions are supported
Supported example:
{
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/step"
}
},
"final_answer": {
"type": "string"
}
},
"$defs": {
"step": {
"type": "object",
"properties": {
"explanation": {
"type": "string"
},
"output": {
"type": "string"
}
},
"required": [
"explanation",
"output"
],
"additionalProperties": false
}
},
"required": [
"steps",
"final_answer"
],
"additionalProperties": false
}
Recursive schemas are supported
Example using # for root recursion:
{
"name": "ui",
"description": "Dynamically generated UI",
"strict": true,
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the UI component",
"enum": ["div", "button", "header", "section", "field", "form"]
},
"label": {
"type": "string",
"description": "The label of the UI component, used for buttons or form fields"
},
"children": {
"type": "array",
"description": "Nested UI components",
"items": {
"$ref": "#"
}
},
"attributes": {
"type": "array",
"description": "Arbitrary attributes for the UI component, suitable for any element",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the attribute, for example onClick or className"
},
"value": {
"type": "string",
"description": "The value of the attribute"
}
},
"additionalProperties": false,
"required": ["name", "value"]
}
}
},
"required": ["type", "label", "children", "attributes"],
"additionalProperties": false
}
}
{
"type": "object",
"properties": {
"linked_list": {
"$ref": "#/$defs/linked_list_node"
}
},
"$defs": {
"linked_list_node": {
"type": "object",
"properties": {
"value": {
"type": "number"
},
"next": {
"anyOf": [
{
"$ref": "#/$defs/linked_list_node"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"next",
"value"
]
}
},
"additionalProperties": false,
"required": [
"linked_list"
]
}
Currently, structured outputs aren’t supported with: Supported models
gpt-5.1-codex version: 2025-11-13gpt-5.1-codex mini version: 2025-11-13gpt-5.1 version: 2025-11-13gpt-5.1-chat version: 2025-11-13gpt-5-pro version 2025-10-06gpt-5-codex version 2025-09-11gpt-5 version 2025-08-07gpt-5-mini version 2025-08-07gpt-5-nano version 2025-08-07codex-mini version 2025-05-16o3-pro version 2025-06-10o3-mini version 2025-01-31o1 version: 2024-12-17gpt-4o-mini version: 2024-07-18gpt-4o version: 2024-08-06gpt-4o version: 2024-11-20gpt-4.1 version 2025-04-14gpt-4.1-nano version 2025-04-14gpt-4.1-mini version: 2025-04-14o4-mini version: 2025-04-16o3 version: 2025-04-16
API support
API version 2024-08-01-preview is the first version that supports structured outputs. The latest preview APIs and the latest GA API, v1, also support structured outputs.