How to use structured outputs with Azure OpenAI in Microsoft Foundry Models

Learn how to improve your model responses with structured outputs

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"]
    }
}

If needed, you can emulate an optional parameter by using a union type with 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
        }
    }

Example of explicit recursion:

{
    "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:

• Bring your own data scenarios.
• Assistants or Foundry Agents Service.
• gpt-4o-audio-preview and gpt-4o-mini-audio-preview version: 2024-12-17.

Supported models

• gpt-5.1-codex version: 2025-11-13
• gpt-5.1-codex mini version: 2025-11-13
• gpt-5.1 version: 2025-11-13
• gpt-5.1-chat version: 2025-11-13
• gpt-5-pro version 2025-10-06
• gpt-5-codex version 2025-09-11
• gpt-5 version 2025-08-07
• gpt-5-mini version 2025-08-07
• gpt-5-nano version 2025-08-07
• codex-mini version 2025-05-16
• o3-pro version 2025-06-10
• o3-mini version 2025-01-31
• o1 version: 2024-12-17
• gpt-4o-mini version: 2024-07-18
• gpt-4o version: 2024-08-06
• gpt-4o version: 2024-11-20
• gpt-4.1 version 2025-04-14
• gpt-4.1-nano version 2025-04-14
• gpt-4.1-mini version: 2025-04-14
• o4-mini version: 2025-04-16
• o3 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.