Prompt Engineering & AI Automation · Unit 4 of 8
Unit 4: Structured output: JSON
Why programs need structure, JSON rules, describing the exact shape with a schema, validating every output, and extraction that is clean enough to use.
Opens the first lesson of this unit in Prompt Engineering & AI Automation. Every lesson is open from the start.
Lesson 1: Why programs need structure
Goal: Read and write valid JSON and explain why automations need it.
A paragraph is perfect for a person and awkward for a program. If a model's answer is going into a spreadsheet, a database or the next step of a workflow, you need structured output: the same fields, in the same shape, every time.
The most common format is JSON (JavaScript Object Notation). It is plain text that almost every programming language and automation tool can read. An object is a set of key-value pairs inside curly braces; a list is called an array and goes inside square brackets.
{
"customer_name": "Dana Ortiz",
"order_id": "88213",
"category": "damaged_item",
"urgent": true,
"items": ["standing desk"],
"refund_requested": null
}
| JSON rule | Right | Wrong |
|---|---|---|
| Keys and text in double quotes | "city": "Leeds" | 'city': 'Leeds' |
| Numbers without quotes or symbols | "total": 1240.5 | "total": "1,240.5 USD" |
| true, false and null in lowercase | "urgent": true | "urgent": True |
| No comma after the last item | ["a", "b"] | ["a", "b",] |
| No comments | (none) | // customer name |
- Structured output
- Model output in a fixed, machine-readable shape, such as JSON with agreed fields.
- JSON
- A plain-text format for structured data: objects of key-value pairs, arrays, strings, numbers, true, false and null.
- Key (field)
- The name in a key-value pair, such as "order_id".
Remember: Double quotes, lowercase true/false/null, numbers without symbols, no trailing commas.
Lesson 2: Describe the exact shape
Goal: Write a schema with types, enums and null for missing values.
To get the same structure every time, describe it exactly. The clearest way is a schema: a description of every field, its type, whether it is required and which values are allowed. You can write it in plain words, as a template to copy, or in the formal JSON Schema language that many tools understand.
Return only a JSON object with these fields:
- "category": one of "billing", "technical", "account", "other"
- "summary": a string of at most 20 words
- "order_id": a string of digits, or null if no order number appears
- "urgent": true if the customer mentions a deadline or a safety issue, otherwise false
Do not add other fields. Do not wrap the JSON in code fences or add any text around it.
Notice the details that prevent trouble later: an enum (a fixed list of allowed values) for category, so one row never says "Billing issue" and another "payments"; null for missing values instead of an invented order number; a rule for when urgent is true; and "only JSON", so there is no friendly sentence before the opening brace.
Many model APIs now offer a structured-output or JSON mode that forces syntactically valid JSON, and some can enforce a full schema. Use those features when you have them. They reduce broken JSON, but they cannot make the values right: a perfectly formatted object can still hold the wrong category or a misread amount.
- Schema
- A description of the fields an output must have, their types and their allowed values.
- Enum
- A field that may only take one of a fixed list of values.
- null
- The JSON value meaning "no value". Use it for information that is missing, instead of guessing.
Remember: Name every field, its type and allowed values. Missing means null. Only JSON, nothing around it.
Lesson 3: Validate every output
Goal: Check outputs against a schema and choose between retry, repair and escalate.
Never feed model output straight into another system. Validate it first: check that it parses as JSON and that it matches your schema. A validator is a small piece of code, and it catches problems before they become wrong invoices or broken reports.
| Common failure | What it looks like | What a validator reports |
|---|---|---|
| Code fences | The JSON wrapped in three backticks and the word json | Not valid JSON: it starts with backticks |
| Chatty text | Sure! Here is the JSON: {...} | Not valid JSON: text before the object |
| Trailing comma | {"a": 1,} | Not valid JSON: unexpected } |
| Missing field | No "urgent" field | Missing required field: urgent |
| Wrong type | "urgent": "yes" | urgent must be true or false |
| Value not allowed | "category": "refund" | category must be one of billing, technical, account, other |
| Cut off | {"summary": "The custo | Not valid JSON: it ended early, often because of the output token limit |
When validation fails, a workflow has three sensible options: retry with the error added to the prompt ("Your last answer was missing urgent; return the full object"), repair simple, safe problems in code (such as stripping code fences), or escalate to a person. What it must never do is pass broken output on silently, or fill a missing value with a guess.
Hands-on lab in the room: JSON output validator. Fix five real-looking model outputs until they pass a strict validator, and see exactly what each error means.
- Validation
- Checking an output against rules (it parses, it matches the schema) before anything uses it.
- Parse
- Read text as structured data. JSON.parse either returns the data or reports an error.
Remember: Parse, then check the schema. On failure: retry with the error, repair safely, or escalate. Never pass it on silently.
Lesson 4: Extraction in practice
Goal: Extract clean, checkable data from messy documents.
Extraction, pulling fields out of messy documents, is one of the most valuable office uses of models: invoices, purchase orders, CVs, forms, contracts and support emails. A few conventions make extracted data clean enough to use.
- Dates in ISO format: "2026-03-01" sorts and compares correctly, unlike "1/3/26" (January or March?).
- Numbers as numbers: 1240.5 plus a separate "currency": "USD", not "1,240.50 dollars".
- Lists as arrays: several line items become an array of objects that all have the same fields.
- Missing means null: never a guess, and never an empty string that looks like a real value.
- Evidence where it matters: a "source_text" field with the exact words a value came from, so a reviewer can check it fast.
Worked example: an invoice becomes data
Invoice text: "Lantern Books Ltd · Invoice LB-2291 · 14 Oct 2026 · 30 x Notebook A5 @ 2.40 · 12 x Desk planner @ 8.75 · Total 160.50 · Payment due within 30 days"
- Header fields: supplier "Lantern Books Ltd", invoice_number "LB-2291", invoice_date "2026-10-14".
- Line items: an array of two objects, such as
{"description": "Notebook A5", "quantity": 30, "unit_price": 2.40}. - Due date: the invoice says "within 30 days", not a date. The prompt says to copy the terms into payment_terms and set due_date to null; code then calculates 2026-11-13.
- Check: 30 × 2.40 + 12 × 8.75 = 72 + 105 = 177, but the invoice says 160.50. The workflow flags the mismatch for a person instead of trusting either number.
Structure plus a simple arithmetic check caught a real discrepancy, perhaps a discount line that the scan missed.
- Extraction
- Pulling specific fields out of unstructured text such as emails, invoices or forms.
- ISO 8601 date
- The year-month-day format, such as 2026-11-17, which sorts and compares correctly.
Remember: ISO dates, numbers as numbers, arrays for lists, null for missing, code for the arithmetic.
Practise it in Prompt Engineering & AI Automation
Each lesson ends with three questions that check you can use the idea, not just recognise it. Wrong answers explain why and come back in Review. The unit ends with a 6-question quiz; pass it with 80% or more to master the unit. Hands-on lab: JSON output validator.
Every lesson is free: no ads, no lives and no paywall.