How it works

The explanation, with examples you can run.

Layer 1: describe the shape

JSON Schema is the common language. Name every field, give it a type, list allowed values with enum, mark what is required, and forbid extra properties. Field descriptions are part of the prompt: the model reads them, so say what each field means and what to put there when the information is absent (often null rather than a made-up value).

1{2  "type": "object",3  "properties": {4    "category": { "type": "string", "enum": ["billing", "bug", "feature", "other"] },5    "priority": { "type": "integer", "minimum": 1, "maximum": 4 },6    "order_id": { "type": ["string", "null"], "description": "As written in the ticket, or null if none is given" }7  },8  "required": ["category", "priority", "order_id"],9  "additionalProperties": false10}

Layer 2: let the provider enforce it

Several APIs now accept a schema and use constrained decoding: at each step, tokens that would break the schema are not allowed, so the output always parses and fits. Older "JSON mode" options only promise valid JSON, not your fields. Tool or function calling is another route: the arguments of a tool call follow the tool's schema (see the next topic).

Check the provider's list of supported schema keywords; some features (certain formats, recursive schemas, very large enums) may be unsupported or limited. Also handle the cases that are not schema output at all: a refusal, or an answer cut off by the token limit.

Layer 3: validate and retry

Schema-valid is not the same as correct. Validate with a real validator (Zod, Pydantic, Ajv or similar), then apply business rules: totals add up, dates are plausible, ids exist in your database. When something fails and you have retries left, send the error back so the model can fix that specific problem.

The example uses a fake model that gets it wrong twice before producing a valid answer, so you can watch the loop.

Your code

// A fake model: returns a canned reply per attempt, ignoring the prompt.
const replies = [
  'Sure! Here is the JSON: {"category": "billing", "priority": 2}',
  '{"category": "payments", "priority": 2, "order_id": "A-1001"}',
  '{"category": "billing", "priority": 2, "order_id": "A-1001"}',
]
let calls = 0
async function fakeModel(messages) {
  return replies[Math.min(calls++, replies.length - 1)]
}

const CATEGORIES = ["billing", "bug", "feature", "other"]
function validate(text) {
  let v
  try { v = JSON.parse(text) } catch { return { ok: false, error: "Reply was not valid JSON. Reply with JSON only." } }
  const errors = []
  if (!CATEGORIES.includes(v.category)) errors.push(`category must be one of ${CATEGORIES.join(", ")}`)
  if (!Number.isInteger(v.priority) || v.priority < 1 || v.priority > 4) errors.push("priority must be an integer 1-4")
  if (!("order_id" in v)) errors.push("order_id is required (use null if absent)")
  return errors.length ? { ok: false, error: errors.join("; ") } : { ok: true, value: v }
}

async function classify(ticket, maxAttempts = 3) {
  const messages = [{ role: "user", content: `Classify this ticket as JSON: ${ticket}` }]
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const reply = await fakeModel(messages)
    const result = validate(reply)
    console.log(`attempt ${attempt}:`, result.ok ? "valid" : `invalid (${result.error})`)
    if (result.ok) return { ok: true, value: result.value }
    messages.push({ role: "assistant", content: reply }, { role: "user", content: `Fix this: ${result.error}` })
  }
  return { ok: false, error: "no valid answer after retries" } // fail closed
}

classify("I was charged twice for order A-1001").then((r) => console.log(JSON.stringify(r)))

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

A few practical rules:

Keep the retry budget small (one or two). If an input fails repeatedly, the prompt or schema needs fixing, and the failure belongs in your evaluation set.
Do not regex JSON out of prose as a long-term solution. It hides problems that schema enforcement or a better prompt would remove.
Version your schemas with your prompts. Adding a required field is a breaking change for every stored example and test.
Keep schemas small and flat where you can. Deeply nested, many-field schemas are harder for models to fill correctly; split one big extraction into a few focused calls if accuracy suffers.

Check yourself

3 questions. Get them all right to finish this topic.

1.A provider's structured output mode guarantees the response matches your schema. Which check do you still need?
2.Validation failed on the second retry as well. What should the code do?
3.What is the difference between a JSON mode and schema-enforced structured outputs?

0 of 3 right so far. Get all three to finish this topic.

Structured outputs your code can trust

How it works

Layer 1: describe the shape

Layer 2: let the provider enforce it

Layer 3: validate and retry

Check yourself

Go deeper