FlowModels

Get responses as JSON: response_format with json_object and json_schema

Published on 11. November 2026

If your application processes the model's response further, you need clean JSON instead of running text. That's what the response_format field is for. It has two levels: json_object gives you valid JSON in any shape, and json_schema lets you specify the exact structure.

The three variants

Value Result
{"type": "text"} normal text, which is also the default
{"type": "json_object"} valid JSON, the model decides the structure
{"type": "json_schema", "json_schema": {…}} JSON that follows your schema

Any JSON with json_object

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "system", "content": "Reply as JSON with the fields subject and priority."},
    {"role": "user", "content": "Customer writes: Our login has been down since this morning."}
  ],
  "response_format": {"type": "json_object"}
}

You should still describe in the prompt which fields you expect. json_object only ensures that valid JSON comes out, not that it contains specific fields. Some providers require the word "JSON" to appear in the prompt. If it's missing from all messages, we automatically add a short note.

A fixed structure with json_schema

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "Customer writes: Our login has been down since this morning."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "subject": {"type": "string"},
          "priority": {"type": "string", "enum": ["low", "medium", "high"]}
        },
        "required": ["subject", "priority"],
        "additionalProperties": false
      }
    }
  }
}

As always, the response is in choices[0].message.content, as text with the JSON inside. Parse it in your code.

If you leave out strict, it defaults to false. With strict: true, the model sticks more closely to the schema, but some providers place stricter requirements on the schema itself. If the provider rejects your schema, you get 400 invalid_field_value with param response_format.

Which models support this

Not every model supports both variants. In GET /v1/models, each model shows under capabilities whether json_object and json_schema are true. If you choose a model without the capability, the API responds with 400 unsupported_for_model instead of quietly returning running text. That way you notice the error right away, not only when parsing. What a model can do: check capabilities, limits, output length and reasoning effort explains how to read the capabilities.

On the /responses endpoint

With /responses, you can use the same response_format field. Alternatively, the endpoint accepts the OpenAI library notation, text.format, where the schema sits flat in the object:

"text": {
  "format": {"type": "json_schema", "name": "ticket", "strict": true, "schema": { … }}
}

Send only one of the two notations. The API rejects both together with HTTP 400, as well as additional fields in text such as verbosity. In the response, the chosen format is under text.format.

If something goes wrong

  • 400 unsupported_for_model: The model doesn't support this variant. Use a different model or fall back to json_object.
  • 400 invalid_field_value with response_format: Check your schema. Common causes are missing required entries or types the provider doesn't support in strict mode.
  • Response is truncated and not valid JSON: The model has usually hit the output limit. Increase max_tokens or reduce the expected response.

Was this article helpful?

Back to Models, limits & errors