It is late, your script has just crashed, and the reason is almost funny. You asked the model for a list of categories. It gave you a list of categories, wrapped in a friendly sentence, inside a code fence, with a closing remark underneath. Your parser wanted JSON. It got prose with JSON somewhere in the middle.
Nothing about the answer was wrong. It simply was not machine readable, and machine readable is the whole point when software is on the receiving end.
Why asking for JSON is not enough
Write return the result as JSON and you will usually get JSON. Usually is the problem. One run in twenty arrives with an explanation in front of it, or a trailing note, or single quotes instead of double. Your code does not care that it was close.
The model is not ignoring you. It has been trained heavily on helpful conversational replies, and helpfulness includes framing an answer. Left to its defaults, it will wrap.
Give the exact shape, not a description of it
The single highest leverage change is to stop describing the format and start showing it. Paste the literal skeleton you want back, with the field names and types spelled out.
A description leaves the model to invent field names, ordering and nesting. A skeleton removes those decisions entirely. It is no longer authoring a structure, it is filling one in.
Be explicit about the boring parts too. Which fields are required. What goes in a field when the answer is unknown. Whether a list can be empty. Every unstated case is a case the model will improvise.
Close the door on the wrapper
Three instructions do most of the work:
- Output the object and nothing else. No preamble, no explanation, no closing line.
- Do not wrap the output in a code fence. Say it directly or you will keep stripping backticks in code.
- Begin the response with the opening brace. Anchoring the very first character is surprisingly effective.
If your provider offers a structured output or JSON mode, use it. Enforcing the grammar at the decoding level is stronger than any instruction you can write, because invalid output becomes impossible rather than unlikely.
Choose the right format for the job
- JSON for anything a program will consume. Universal, compact, easy to validate.
- XML style tags when the payload is long prose. Tags survive messy content better than braces do, and models are very comfortable closing a tag.
- Plain delimited lines for simple flat lists. Do not reach for JSON when a newline would do.
Keep the thinking out of the payload
Reasoning often improves answer quality, and it also pollutes structured output. The fix is to give the reasoning its own place: a dedicated field inside the object that your code reads and discards, separate from the field your application actually uses.
The model still gets to think. Your parser still gets clean data. Nobody has to choose.
Validate, then decide what happens on failure
Assume malformed output will happen eventually and plan the branch now.
- Parse inside a try block. Never trust the string.
- Check required fields exist and hold the right types before using them.
- On failure, retry once with a short instruction to return only the object.
- Log the raw text when it fails. That log is where you learn what your prompt is missing.
The habit worth building
Before a prompt goes anywhere near production, run it against five deliberately awkward inputs: a normal one, an empty one, a very long one, one full of quotes and special characters, and one written to confuse it. If all five parse, you have something you can build on.
The Build Fail-Proof AI Prompts guide covers schema enforcement and silent reasoning in full, and the production readiness checklist turns the testing habit into sixteen concrete checks.