Structured Outputs

A structured output is a model reply shaped as data — usually JSON — so your program can read fields, not only show prose to a human.

Until now, a good reply looked like free text:

2 + 2 is 4.

That is fine for a person. A program that needs a number in a variable prefers something like:

{
  "answer": 4
}

Free text vs structured data

Request (ordinary turn — reply can be any wording):

{
  "model": "some-model",
  "messages": [
    {
      "role": "user",
      "content": "Alice is 30 years old. Extract the name and age."
    }
  ]
}

Response (prose — hard for code to use safely):

{
  "message": {
    "role": "assistant",
    "content": "Sure! The person's name is Alice, and she is thirty years old."
  }
}

Your program would have to guess where the name and age sit inside that sentence.

Structured means you ask the API for a reply in a fixed shape, for example:

{
  "name": "Alice",
  "age": 30
}

Now your program can do name and age as fields — no sentence parsing.

A schema is the shape you want

A schema describes the fields and types you expect — for example:

You send that shape with the request (field names vary by company). The model is steered to reply as JSON that matches it.

  Your program
  ┌────────────────────┐
  │  prompt + schema   │
  │  (name, age, …)    │
  └─────────┬──────────┘
            │
            ▼
         Server / model
            │
            ▼
  ┌────────────────────┐
  │  JSON reply        │
  │  {"name":"Alice",  │
  │   "age":30}        │
  └────────────────────┘

Companies differ on exact knobs (response_format, response_mime_type, schema, and so on). The job is the same: “reply as JSON with these fields.”

What your program does next

1. Send the prompt (and the schema / JSON mode)
2. Read the assistant text (it should be JSON)
3. Parse that JSON into values your language understands
4. Use the fields

If parsing fails, the reply was not valid JSON (or not the shape you expected). Treat that as an error path — retry, repair, or fail clearly. Do not pretend a bad string is structured data.

See it in Code

The Code panel asks the model for a small person record (name, age) as JSON, then prints the reply text. Same idea in Python, Java, Go, and TypeScript — SDK field names differ; the shape job does not.

Cast for this beat

You now have the language-model foundation: model, API key, turn, roles, history/context, and structured replies.

Next section: Agents — when your program can do more than chat in text, and the model can use tools.