# Structured output

Constrain the reply to machine-readable JSON with `response_format` — either valid JSON of any shape, or JSON matching a schema you supply.

## JSON mode

`{ "type": "json_object" }` guarantees the reply parses as JSON, but says nothing about its shape. Describe the fields you want in the prompt as well — the constraint enforces syntax, not structure.

```
{
  "model": "IFM/K2-Horizon-375B-A23B",
  "messages": [{ "role": "user", "content": "List three UAE emirates with populations." }],
  "response_format": { "type": "json_object" }
}
```

## JSON Schema mode

`{ "type": "json_schema" }` pins the exact shape. Decoding is constrained to your schema, so the reply validates by construction and you can skip defensive parsing.

```
"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "emirate_list",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "emirates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "population": { "type": "integer" }
            },
            "required": ["name", "population"]
          }
        }
      },
      "required": ["emirates"]
    }
  }
}
```

Keep schemas shallow and name fields the way you would in a prompt — deeply nested or cryptically named schemas cost tokens and degrade the content of the answer even though it stays valid.

## With reasoning

The constraint applies to `content` only. `reasoning_content` is free-form prose and is never JSON — parse the two fields separately, and keep replaying the trace as described in [Multi-turn conversations](https://docs.ifm.ai/docs/multi-turn.md).

## Failure modes

A schema the model cannot satisfy usually surfaces as a truncated reply with `finish_reason: "length"` rather than an error — the constraint keeps the output valid right up to the token limit. Raise `max_tokens`, then simplify the schema. Unsupported JSON Schema keywords are rejected at request time with a `400`; see [Errors](https://docs.ifm.ai/docs/errors.md).

_Last updated: September 2, 2026_