Loading...
System Design and AI Engineering, by Roni Das. 980 interactive lessons.
Start LearningAI Engineering · Advanced · LLM and GenAI Ops
Constraining a model to return valid JSON matching a schema, so downstream code can rely on it. The foundation of reliable tool calling.
In short
Structured output means making a model reply in a fixed data shape, usually JSON that matches a schema, so code can read it reliably. A schema guarantees the shape, not the truth: it can turn a disallowed answer into an allowed but wrong one.
In short
Structured output means making a model reply in a fixed data shape, usually JSON that matches a schema, so code can read it reliably. A schema guarantees the shape, not the truth: it can turn a disallowed answer into an allowed but wrong one.
Learn it in the course
This page is the free part.
₹999 in India$49 everywhere elseonce, for the whole course
The AI Engineering course covers Structured Output across a run of lessons, not one page. These 4 alone are about 218 minutes of step-by-step reading, every one with code you run in the browser, all with a quiz.
Lesson 1's 40 messages, answered as a JSON object with three fields, asked for four ways on two models: in words, with Ollama's JSON mode, with a JSON schema, and with the schema alone. Every way gave valid JSON 40 of 40 times. The schema stopped one invalid category ('travel') but turned it into a valid wrong one; without the words, summaries grew past the limit; and with a token limit of 20, a schema did not stop the JSON from breaking.
Forcing a model to reply with one JSON answer field is great for programs. On 70 maths problems with known answers, two small models collapsed from 46 and 70 right to almost none when the only room was the answer box. A steps field before the answer won most of it back, but not all. When only asked nicely for JSON, one model left the calculation unworked in the answer field, and the other ignored the rule and wrote its working anyway.
OWASP LLM05. Hardening the prompt does not help if you paste the answer into a query. Measured: strict JSON parsing leaked as many dangerous payloads as a regex, and rejected good answers too.
I gave four prompted models, from 3B to 14B, the full house rules for the ticket task and a JSON schema, and scored every field of every reply on the 140 test messages. Every reply was valid JSON and the order number was right almost every time, but the whole ticket was right on only 50 to 93 of 131 fully gold messages. Reading every wrong answer shows which rules slip: a bigger model fixed extra words in the item and questions read as requests, but not comments that ask for nothing, which even qwen2.5:14b got wrong 11 times out of 13. Twenty-two fields were wrong in all four models. Those are the first thing a fine-tune has to beat.
all part of
AI Engineering
210 lessons · about 219 hours · 10 free to read
₹999in India, by UPI
$49everywhere else, by PayPal
You own this course
Continue with Asking for a Format: Words, JSON Mode and a Schemapay once,
yours for life
When code uses a model's reply, it usually needs several separate values: a category, a short summary, a yes or no. If the model words these differently each time, the code that pulls them out breaks. The common fix is to ask for JSON, a standard text format for data. A JSON object is a set of named fields, such as {'category': 'billing', 'needs_human': true} written with double quotes.
There are three levels of asking. You can describe the fields in words. You can switch on JSON mode, which in Ollama is the option format set to json: the reply must be valid JSON, but nothing says which fields it has. Or you can pass a JSON Schema, a description of the exact fields, their types, which are required, and for some fields an enum, a fixed list of allowed values.
The last level is what most tools call structured output or structured outputs. Ollama takes the schema in its format option, OpenAI's API accepts a JSON Schema in its response format, and llama.cpp can enforce grammars. The details differ, but the goal is the same: a reply that code can parse without guessing.
A model writes by choosing one token at a time from odds over its whole vocabulary. With a schema, the server turns the schema into rules about which characters may come next, and before each token is chosen it removes every token that would break those rules. This is often called constrained decoding. If the schema says a field is a whole number, only digit tokens are allowed at that point.
Ollama applies these rules while the model writes and does not check the finished reply again afterwards. Other servers may work differently, and some check only after writing. Either way, the schema limits which tokens appear. It does not limit how many tokens the model may write; that is a separate setting, the token limit.
Because a model writes left to right, field order matters. If the answer field comes before a reasoning field, the answer is written before any reasoning exists, and reasoning written afterwards cannot change it. Some tools sort fields by name, which can silently put answer before steps, so check real replies.
A lab gave 40 customer messages to two small models, qwen2.5:3b and llama3.2:3b, at temperature 0, asking for three fields: category (one of billing, delivery, returns, account), summary (at most 12 words) and needs_human (true or false). Asked in words, with JSON mode, or with a schema, every way produced valid JSON 40 of 40 times on both models. JSON mode replies were identical, character for character, to the replies asked for in words.
The schema changed one reply out of 80, and that reply is the one that matters. For 'Do you ship to Iceland?', a delivery question, qwen2.5:3b asked in words answered with the category 'travel', which is not allowed, so a code check rejects it. With the schema, 'travel' was impossible, so the model wrote 'billing', then stayed consistent with it: the summary became 'Iceland trip billing discrepancy detected' and needs_human became true. Every format check passed. The answer was wrong. Format passes rose from 39 to 40; right categories stayed at 39.
Dropping the written rules and sending the schema alone showed what a schema cannot say. On qwen2.5:3b, median summary length grew from 6 to 11.5 words, and only 24 of 40 stayed within 12 words, against 40 of 40 with the words. needs_human went from true on 38 of 40 messages to true on none. JSON Schema cannot count words at all; its maxLength rule counts characters.
A second lab gave 70 maths word problems with known answers to llama3.2:3b and qwen3:4b in four formats. Free text ending with an 'Answer:' line scored 46 and 70 right. JSON asked for politely scored 1 and 0 when read strictly. An enforced schema with only an answer field scored 1 and 5. An enforced schema with a steps field before the answer scored 35 and 47.
The details explain the collapse. llama3.2:3b's one right answer in the answer-only format was a problem whose answer was 0, and qwen3:4b put 0 in the box on 35 of 70 problems. Asked politely, llama3.2:3b wrote replies such as {'answer': 59 + 4 * 3}, a calculation where a number should be; that is invalid JSON, yet 10 of 11 such calculations were set up correctly. qwen3:4b wrote its working first and JSON at the end: a strict parser read none of the 70 replies, a lenient one found the right answer in all 70.
A steps field gives room, not a guarantee. qwen3:4b left the steps field empty on 15 problems and got 0 of those right; when it wrote steps, it got 47 of 55. Room also costs tokens: llama3.2:3b averaged about 141 tokens free, 7 with one answer box and 100 with steps first. The lab covered maths only, two small models, and changed the instruction wording along with the format.
Check whether the reply was cut off before anything else. In Ollama the done_reason field says 'length' when the token limit was hit. With a 20-token limit, 0 of 40 qwen2.5:3b replies and 14 of 40 llama3.2:3b replies were valid JSON, with or without a schema. A schema shapes each token; it cannot make a reply longer than the limit. Set the limit well above your longest expected reply.
Then parse and treat failure as normal: catch the parse error and decide in advance whether to retry or send the case to a person. Check every field, including the rules a schema cannot express, such as a word limit. Keep those rules written in the prompt as well, because the schema only fixes shape and type. A field that is true for almost every input, like needs_human above, is valid and useless; define when it should be true.
For tasks that need reasoning, put a steps field before the answer and count empty ones. When a correct answer may not exist, consider an 'other' or 'unsure' value so the model is not forced into a wrong allowed value; that was not tested in these labs, so measure it. Finally, compare a sample of replies with known answers. That is the only check that would catch the Iceland reply.
Ollama
Ollama's format option accepts either the string json or a JSON Schema, and with a schema it restricts which tokens the model may write.
OpenAI Structured Outputs
OpenAI's API can take a JSON Schema in the response format and, in strict mode, returns replies that match it.
llama.cpp grammars
llama.cpp can constrain generation with GBNF grammars and can convert a JSON Schema into such a grammar.
Outlines
Outlines is an open-source Python library for constrained generation that makes a model's output follow a JSON Schema, regular expression or grammar.
It is a reply forced into a fixed data shape, usually JSON matching a schema, so a program can parse it. The server removes any next token that would break the schema while the model writes. It guarantees fields, types and allowed values, not correct content.
JSON mode guarantees the reply is valid JSON but says nothing about which fields it contains. Structured outputs use a JSON Schema, so the reply must have the named fields, the right types and only allowed values. Prefer a schema when your server supports one.
It can on tasks that need reasoning. In a lab with 70 maths problems, an enforced one-field answer dropped llama3.2:3b from 46 right to 1 and qwen3:4b from 70 to 5. Putting a steps field before the answer brought them back to 35 and 47. On a simple classification task, a schema cost nothing in tokens.
The reply hit the token limit before the closing bracket. A schema controls which tokens are written, not how many. Check done_reason for 'length', treat those replies as failures, and raise the limit well above your longest expected reply.
No. JSON Schema has no word count; maxLength counts characters, and forcing it can make the model write very short text. Put word limits in the prompt's instructions and check them in code.
Structured Output Costs Right Answers: One JSON Box, Measured
Forcing a model to reply with one JSON answer field is great for programs. On 70 maths problems with known answers, two small models collapsed from 46 and 70 right to almost none when the only room was the answer box. A steps field before the answer won most of it back, but not all. When only asked nicely for JSON, one model left the calculation unworked in the answer field, and the other ignored the rule and wrote its working anyway.
Improper Output Handling: The Model's Answer Is Untrusted Input
OWASP LLM05. Hardening the prompt does not help if you paste the answer into a query. Measured: strict JSON parsing leaked as many dangerous payloads as a regex, and rejected good answers too.
Where Prompts Slip: The Same House Rules for Four Models, Checked Field by Field
I gave four prompted models, from 3B to 14B, the full house rules for the ticket task and a JSON schema, and scored every field of every reply on the 140 test messages. Every reply was valid JSON and the order number was right almost every time, but the whole ticket was right on only 50 to 93 of 131 fully gold messages. Reading every wrong answer shows which rules slip: a bigger model fixed extra words in the item and questions read as requests, but not comments that ask for nothing, which even qwen2.5:14b got wrong 11 times out of 13. Twenty-two fields were wrong in all four models. Those are the first thing a fine-tune has to beat.
Training a Small Model on 500 Tickets: What LoRA Changes, and How It Compares With a Prompt
I trained three small Qwen2.5 models (0.5B, 1.5B and 3B) with LoRA on the 500 training tickets, gave them a one-line prompt instead of the house rules, and scored them field by field against four prompted models on the same 140 test messages. Under 1% of each model's weights was trained, into an add-on of 12 to 27 MB. The fine-tuned 0.5B got 93 whole tickets right of 131, the same as the prompted qwen2.5:14b, but on different messages: 22 right only in one, 22 right only in the other, sign test p = 1. On the 13 comments that ask for nothing, which the prompted models almost always got wrong, the fine-tunes got 11 or 12 right; they also made mistakes the prompts did not.
An Attack on a Fine-Tuned Model: One Override Sentence, Two Fine-Tunes and Two Prompts
I added the prompting chapter's override sentence to all 140 ticket test messages and sent them to four models, each as built in this chapter. The fine-tuned 0.5B ignored it: 140 of 140 replies valid JSON, 93 whole tickets right, the same as without the attack. The fine-tuned 1.5B, trained the same way, broke the format on 76 of 140: 47 of those wrote to the customer as the shop, many claiming something had been done, and its whole tickets fell from 102 to 23. The two prompted models stayed valid JSON because of their schema, but their content moved: the 14B sent 23 more tickets to account and fell from 93 to 80.
Tool Calling
When a model emits a structured request to run a function, and an orchestrator executes it and feeds the result back. The model never runs anything itself, so the orchestrator validates every call.
AI Agent
A language model placed in a loop: it decides an action, calls a tool, reads the result, and repeats until done. The hard part is that per-step errors compound over many steps.
Prompt Engineering
Writing and structuring the instructions given to a language model to get reliable output. In 2026 the craft has moved from clever wording to schemas, context layout, and evaluation.
RAG (Retrieval-Augmented Generation)
A pattern that retrieves relevant text from an external index and puts it in the model's prompt so the answer is grounded in current, verifiable facts rather than the model's memory.
Agentic RAG
Agentic RAG is RAG where a language model runs the search in a loop. It decides whether to search, what to search for and where. Then it checks if the text it found answers the question.
Embedding
A list of numbers that represents the meaning of a piece of text, so that similar meanings sit close together in vector space. The same model must embed both the corpus and the query.
This page explains the idea. The "Asking for a Format: Words, JSON Mode and a Schema" lesson builds it up step by step, with diagrams. It is part of the AI Engineering course, which has 210 lessons. 10 of them are free to read. You pay once and keep it for life, with no subscription.
Open the Asking for a Format: Words, JSON Mode and a Schema lessoncourse 2
Take models from notebook to production, with labs on real models.
Asked about Structured Output in an interview?
Each question has why it is asked, a full answer, what the interviewer listens for, the follow-ups, the common mistakes and a diagram (180 diagrams in all). A PDF you keep, junior to staff level.
India: UPI, cards or netbanking through Razorpay. Elsewhere: PayPal. Download at once from My packs.
