Chapter 5 · Control the format#

The big idea#

If another person reads the answer, a paragraph is fine. If a program reads it, you need a strict shape such as JSON, CSV or a fixed template. Tell the model the exact format, name the fields, and say “output only” so no friendly introduction breaks your parser.

Everyday example: A paper form with boxes gets you data you can file. A blank page gets you a story. When you want to feed the answer into a spreadsheet, hand over the form.

In plain words

Show the exact keys you want. A tiny template inside the prompt is the most reliable way to get consistent output.

A picture#

Say the shape of the answer and a program can use it.

Before and after#

Replies below are typical examples to show the difference. Your model will word things differently, so run the prompts yourself.

Example 1 · Extraction#

Before

Extract the order details from this message:

"Hi, order 4821, I bought 2 blue notebooks and want to change the address."

Typical reply

Sure! Here are the details I found: The order number is 4821. The customer bought 2 blue notebooks. They would like to change the delivery address.

After

Extract the order details from the message below. Return only JSON with keys: order_id (number), item (string), quantity (number), wants_address_change (true/false). No other text.

Message: "Hi, order 4821, I bought 2 blue notebooks and want to change the address."

Typical reply

{"order_id": 4821, "item": "blue notebook", "quantity": 2, "wants_address_change": true}

Prompt checker (code/promptcheck.py, columns T C A F L E D):

before   3/7  [Y Y . . Y . .]  missing: audience, format, example, delimiters
after    4/7  [Y Y . Y Y . .]  missing: audience, example, delimiters

Why it works. The first answer is correct and useless to code: you would have to parse English. The second can go straight into json.loads.

Example 2 · Reports#

Before

Compare Python and JavaScript.

Typical reply

Python and JavaScript are both popular. Python is known for readability, while JavaScript runs in browsers. Python is used in data science, whereas JavaScript is used for web development... (a long paragraph)

After

Compare Python and JavaScript for a beginner choosing a first language. Use a markdown table with columns: Feature, Python, JavaScript, and exactly 4 rows (syntax, where it runs, typical jobs, learning curve). Add a one-line recommendation below the table.

Typical reply

| Feature | Python | JavaScript |
|---|---|---|
| Syntax | Clean, indentation-based | C-style braces |
| Runs | On your computer or a server | In every browser, plus servers |
| Typical jobs | Data, automation, AI | Websites, apps |
| Learning curve | Gentle | Moderate (quirks) |

**Recommendation:** start with Python unless you want to build websites first.

Prompt checker (code/promptcheck.py, columns T C A F L E D):

before   1/7  [Y . . . . . .]  missing: context, audience, format, limits, example, delimiters
after    5/7  [Y Y Y Y Y . .]  missing: example, delimiters

Why it works. A table makes comparison scannable. Fixing columns and row count removes layout guesswork.

Prove the format with code#

You can test the format automatically. The checker below is from code/evalkit.py:

import json

def valid_json(reply):
    try:
        data = json.loads(reply)
    except ValueError:
        return False
    return isinstance(data, dict)

print(valid_json('{"order_id": 4821}'))
print(valid_json('Sure! Here are the details: ...'))

True
False

If the second kind of reply ever comes back, your prompt needs a stricter format instruction (see chapter 13).

Rules of thumb#

Name every field and its type.
Say “Output only the JSON” (or table, or list) to remove greetings.
Give a sample of the exact shape if the format is unusual.

Common mistakes#

Asking for JSON but not naming the keys, so every reply uses different ones.
Forgetting to say what to do when a value is missing (use null).
Trusting the format without validating it in code.

Try it yourself#

Write the format instruction to get three tags for a blog post as a comma-separated line.
What should the prompt say if the order number may be absent?
Why validate the reply in code even with a strict prompt?

Answers

“Return exactly 3 lowercase tags, comma-separated, on one line, with no other text.”
“If a field is not in the message, use null for it.” This stops the model from inventing a value.
Models sometimes ignore format instructions. A validator catches the failure and lets you retry or log it.

Some formats are easier shown than described. Next: few-shot examples.