# Structured output

Give a schema and the answer conforms to it. Only a model whose catalog entry can be held to a schema is asked, so a model that can’t is refused before the call instead of returning malformed JSON.

## Ask for a schema

On [`POST /models`](/docs/gateway/reference/chat/), send `responseSchema`. It needs a model whose
`capabilities.structuredOutput` in the [catalog](/docs/gateway/reference/list-models/) is `jsonSchema`; when no model
the call names can, the call is refused with `422` before any provider is called.

```json
"responseSchema": {
  "type": "object",
  "properties": {
    "city":       { "type": "string" },
    "celsius":    { "type": "number" },
    "conditions": { "type": "string" }
  },
  "required": ["city", "celsius", "conditions"]
},
"parameters": { "strict": true }
```

`strict` holds the provider to the schema where it supports a strict mode. The answer still arrives as a `content`
message whose `value` is the JSON text.

```json
{ "type": "content", "value": "{\"city\":\"Lagos\",\"celsius\":31,\"conditions\":\"humid, scattered thunderstorms\"}", "data": {} }
```

The serialized schemas of a request, `responseSchema` and every tool's `parameters` together, may be at most 256 KiB.

## Which models can

`capabilities.structuredOutput` says what an offering can be held to:

| Value | Meaning |
|---|---|
| `jsonSchema` | The answer can be held to a schema you give. `responseSchema` needs this. |
| `jsonObject` | The answer can be held to JSON, without a schema. |
| `none` | Neither. |

The catalog's Supports filter calls both `jsonSchema` and `jsonObject` Structured output.

## On Chat Completions

[`POST /v1/chat/completions`](/docs/gateway/reference/chat-completions/) has no `responseSchema`: send OpenAI's
`response_format`, which goes to the provider as you wrote it. A call with a `json_schema` response format is tried
first on the offerings that take one, and the others stay behind them as backup. Anthropic is sent `json_schema` in
its own form; Gemini and Vertex take `json_schema` and `json_object`.

```json
"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "weather",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": { "city": { "type": "string" }, "celsius": { "type": "number" } },
      "required": ["city", "celsius"]
    }
  }
}
```