Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Structured Output and Tool Use

Getting Structured Output (JSON) from a Model

Ask a model for JSON that your program can parse: schemas, field descriptions, examples, enums and strict output modes. Includes runnable Python schema tools.

Prose is great for people, but programs need structure. When a model's answer feeds a database, a UI or another function, you want structured output: usually JSON with known fields and types. Getting it reliably takes a clear schema, a good prompt and a validation step, because even strong models occasionally produce malformed or surprising output.

Why structure matters

Compare the two replies to "extract the order details":

TEXT
Sure! The customer is Ana Ruiz and she ordered two copies of "Dune" for $31.98.
JSON
{"customer": "Ana Ruiz", "items": [{"title": "Dune", "qty": 2}], "total": 31.98}

The first needs fragile text parsing. The second can be loaded in one line and checked field by field. Structured output turns the model into a component with an interface.

Three levels of reliability

  1. Prompt only. You describe the JSON and ask for it. Works most of the time; you must validate and sometimes retry.
  2. JSON mode. Many APIs offer a setting that guarantees syntactically valid JSON (but not your schema).
  3. Schema-constrained output. Some APIs accept a JSON Schema and constrain generation so the reply conforms to it. This is the strongest option where available, but the details differ by provider, and supported schema features are limited.

Whichever level you use, validate in your own code. Treat the model like any external input.

Writing a prompt that gets JSON

Good structured-output prompts share a pattern:

  • State the task and the exact fields with types and meanings.
  • Give the allowed values for categorical fields (an enum).
  • Say what to output for missing data (null, empty string, "unknown").
  • Say "Return only the JSON, with no explanation, no markdown fences".
  • Show one example of the shape.
TEXT
Extract the order details from the message.
Return only a JSON object with these keys:
- "customer": string, the customer's full name, or null if not stated
- "items": array of objects {"title": string, "qty": integer}
- "priority": one of "low", "normal", "urgent"
Use null for any value the message does not state. Do not invent values.

Message:
"""
Hi, Ana Ruiz here. Please send 2 copies of Dune ASAP.
"""

Build the prompt from a schema

Rather than hand-writing the field list, derive it from a schema you also use for validation, so the prompt and the checker cannot drift apart. The block builds a prompt from a small schema description.

Python Generate the field list from one schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Parsing and checking the reply

Python's json.loads parses the reply, and your code checks the contents. The next block validates replies against the same style of schema by hand. (In real projects you might use a validation library such as pydantic or jsonschema; here we write the checks out so you can see what they do.)

Python Validate a model reply (hand-written checks)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The third reply shows the most common failure: extra chatter around the JSON. The next lesson covers extraction and repair.

Design schemas models can follow

  • Keep it flat and small. Deeply nested, 40-field schemas are error-prone. Split big extractions into several calls.
  • Use enums for categories rather than free text.
  • Put the reasoning first if you want it: a "reasoning" string field before the answer field lets the model think before it commits, because generation goes in order.
  • Name fields clearly (due_date beats d). The names are part of the prompt.
  • Use ISO formats for dates (2026-03-14) and plain numbers for amounts, with the currency in its own field.
  • Allow null for optional data so the model is not forced to invent.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should you always do even if the API guarantees valid JSON?

    Valid JSON syntax does not mean the right fields, types and values. Treat model output as external input.
  2. 2. How should the prompt handle missing data?

    Without a rule for missing values, models often invent plausible ones.
  3. 3. Why derive the prompt's field list from the same schema used for validation?

    One source of truth avoids contradictions between what you ask for and what you accept.
  4. 4. Why might a "reasoning" field come before the "answer" field in the schema?

    Output is produced token by token, so earlier fields can inform later ones.

Summary

  • Structured output turns the model into a component with an interface; JSON is the usual format.
  • Reliability ranges from prompt-only to JSON mode to schema-constrained output; always validate in your code.
  • Specify fields, types, enums, a null rule, "return only JSON" and an example.
  • Keep schemas small and flat with clear field names; put reasoning fields before answers.

Next: Validating and Repairing JSON