Session 5· 02· 10 min

JSON Mode Basics

What you'll learn
  • ▸Enable response_format: { type: "json_object" }
  • ▸Get guaranteed valid JSON output instead of plain text
  • ▸Understand the limitation — the model picks its own keys

The problem we are solving

In lesson 01 the model returned prose. Great for humans, useless for code that needs to parse fields. JSON mode is the first step up — you tell the API "reply with valid JSON, no matter what" and the API guarantees it.

Plain text
lesson 01
  • •Free-form natural language
  • •Not parseable by code
  • •Shape is unpredictable
  • •Fine for chat, terrible for data
JSON mode
this lesson
  • •Guaranteed valid JSON you can json.loads()
  • •But the MODEL picks the keys
  • •Still unpredictable SHAPE — just parseable
  • •Step 1 of 3 toward fully structured output

The code

02_json_mode_basics.py
response = client.chat.completions.create(
    model=model,
    messages=[
        {"role": "system",
         "content": "You are a helpful assistant that returns information in JSON format."},   ①
        {"role": "user",
         "content": "Return JSON with keys: topic, difficulty, tips (array of 3 strings) for learning function calling."},
    ],
    response_format={"type": "json_object"},                    ②
)

raw = response.choices[0].message.content or "{}"              ③
print(raw)
print(json.loads(raw))                                          ④
①You still have to ASK the model for JSON in the prompt — response_format alone does not suggest keys.
②The magic line: response_format={"type": "json_object"} forces the output to be valid JSON.
③The content is a JSON STRING, not a dict. Always fall back to "{}" in case the model returns empty.
④json.loads() turns the string into a real Python dict you can index.

Run it

$ python 02_json_mode_basics.py
Limitation — no shape guarantee
JSON mode guarantees parseable JSON. It does NOT guarantee which keys exist. The model decides. If you need an exact shape, you need a schema (lesson 03).

Knowledge check

Knowledge Check
What does response_format={"type": "json_object"} guarantee?
Code Check
What type is response.choices[0].message.content in JSON mode?
Recap — what you just learned
  • ✓response_format={"type": "json_object"} guarantees parseable JSON
  • ✓You must still ASK for JSON in the prompt, and the model picks its own keys
  • ✓json.loads() turns the response string into a Python dict
Next up: 03 — Schema Output Intro