JSON Prompt Builder

Why prose breaks code and JSON doesn't

Ask a model for "the candidate's name, salary and start date" and you get a nicely written paragraph. Ask twice and you get two different paragraphs. One says "around $85k," the next "85,000 USD annually," a third opens with "Sure! Here's what I found." Your parser has no chance.

The problem isn't accuracy — the model may be right every time. It's that free text has no contract. Nothing guarantees the salary appears before the date, that a missing field is omitted rather than described, or that the answer skips the preamble. Every regex you write to cope is a bug waiting for a slightly different phrasing.

JSON gives you the contract. Keys are fixed, types are fixed, null means "not found" every time. Your code reads data.salary instead of hunting for a dollar sign. When the model gets it wrong you find out at the parse step, not three functions downstream.

If a person reads the output, prose is fine. If code reads it, use JSON.

Design a schema the model can actually hit

Models satisfy simple schemas reliably and complex ones intermittently. Rules that hold up:

• Flat beats nested. Two levels is comfortable. Four is where braces start closing in the wrong place. contact_email is safer than contact.channels.email.primary.
• Be explicit about types. Say "salary must be a number, not a string." Models default to strings when unsure.
• Use null, never omit. Missing keys break data.x.y in ways missing values don't.
• Fix your enums. "status must be exactly one of: open, closed, pending" gets three values. "status: the current status" gets fifteen phrasings of the same three.
• Name keys like a developer would. snake_case, no spaces. The model writes a lot of JSON already.
• Skip fields you won't use. Every extra key is another chance to invent a value.

Show the shape rather than describing it. A literal example with placeholders beats a paragraph of spec:

Instructions that kill stray prose and code fences

Three failure modes cause nearly every unparseable response: a preamble, a markdown fence, a trailing explanation. Put these near the end, where they're read last:

• "Return ONLY the JSON object. No prose, no explanation, no markdown code fences."
• "Your entire response must start with an opening brace and end with a closing brace."
• "Do not wrap the output in backticks."

That second line does the heaviest lifting. It's a check the model can verify against its own first token, far more reliable than a general "no extra text."

Help yourself on the parsing side too. Strip leading and trailing fences before parsing — three lines of defensive code that saves a retry. And drop temperature to 0. Creative sampling is exactly wrong here.

If one model keeps adding preambles, that's usually a phrasing quirk, not a capability gap. The ChatGPT prompt generator and the Gemini prompt generator handle per-model wording, and the analyzer flags instructions that quietly invite commentary.

Arrays, optional fields, and the empty case

Arrays are where extraction prompts get sloppy. Say how many, and what happens when there are none.

"Return [] if none apply" stops the model writing "none" into an array slot. The cap stops it padding a short document to look thorough. For optional objects, prefer null over omission — one branch in your code instead of two.

Validate, retry, and where native modes fit

Never trust the first parse. The loop that survives production:

1. Parse. If it throws, strip fences and whitespace, parse again.
2. Validate against a real schema — Zod, Pydantic, JSON Schema. Check types and required keys, not just that it's valid JSON.
3. On failure, retry once with the error appended: "Your previous output failed validation: expected number for salary, got string. Return corrected JSON only."
4. After two failures, log the raw output and fall back. Don't loop.

That retry fixes most failures first try, because you've turned a vague miss into a specific correction.

Now the part people skip: most providers ship native structured output — JSON mode, response schemas, function calling. Use it where it exists. The API constrains decoding, so malformed JSON becomes nearly impossible. But it enforces shape, not sense. A schema-valid response can still put the recruiter's name in company. The prompt carries the semantics: what each field means, when null applies, which enum fits. The two are complementary. OpenAI's guidance covers the API side; the fundamentals guide covers the patterns underneath all of this, and the optimizer tightens a bloated extraction prompt without dropping the constraints that matter.