Blog
JSON Prompt: Fix Invalid Output and Missing Fields
Copy a JSON prompt that defines fields, types, evidence, and missing values. Compare JSON mode with structured outputs and validate results in three layers.
In this article
A useful JSON prompt defines the fields, allowed values, evidence requirements, and behavior when information is missing. ‘Return JSON only’ is not enough: valid syntax, schema compliance, and correct facts are separate requirements. Use the support-message template below, then validate parsing, structure, and business meaning independently. The examples describe intended behavior and are not claims that a particular model passed a benchmark.
1. Define the JSON prompt's data contract first
Decide what the downstream application actually needs. A support router might require category, summary, evidence, and needs_review rather than a paragraph explaining everything the model considered. Document every field's name, type, required status, allowed values, and meaning in one place. Keep the prompt examples and validator aligned with that contract whenever either changes.
Distinguish an unknown value from a valid zero, false, or empty string. Zero can be a real amount; false is already a decision. If absence matters, explicitly allow null, an omitted field, or a dedicated status that the application understands. Do not choose a convenient placeholder that silently becomes a real business fact later in the pipeline.

| Field | Type and values | Missing-information behavior |
|---|---|---|
| category | billing, access, or other | Use other when no category is established |
| summary | Short string based on the message | Reject empty input before requesting a result |
| evidence | Source quote or null | Use null if no supporting quote exists |
| needs_review | Boolean | True for ambiguous, multiple-intent, or unsupported cases |
2. Copy this JSON output prompt
State that the input is data to analyze rather than a place for new instructions. That expresses the task boundary; the application must still treat incoming messages as untrusted. A JSON object is not authorization to refund a payment, delete an account, or invoke another sensitive action. Keep extraction separate from the permissions required for subsequent actions.
This example selects one primary category. A message that reports both duplicate billing and failed login should trigger review instead of hiding the second issue. If your router supports multiple labels, change the field to an array and update its schema, examples, and consumer together. Do not quietly change the output shape inside the prompt alone.
Support-message classification example
Use only the support message inside <message>.
Return one JSON object, without explanations, Markdown fences, or extra fields.
category: billing, access, or other. Use other for multiple intents or when no unique category is supported.
summary: one sentence, with no facts beyond the message.
evidence: a short exact source quote, or null when unavailable.
needs_review: true for ambiguity, multiple intents, or insufficient evidence.
<message>
[Support message]
</message>
Example input: I cannot log in.
Example output:
{
"category": "access",
"summary": "The user reports being unable to log in.",
"evidence": "cannot log in",
"needs_review": false
}Load this template →3. JSON mode vs structured outputs: choose the right constraint
A plain prompt describes desired behavior, but the model may still add a code fence, explanation, or inconsistent fields. Some services provide a JSON mode focused on valid JSON. Some models and interfaces support schema-constrained structured outputs, which can enforce more of the shape. Verify the actual provider, supported schema subset, and exceptional responses before relying on either option.
None of these modes establishes factual correctness. A perfectly shaped object can contain a wrong category or an invented quotation. Also, typing ‘use structured outputs’ in a chat conversation does not prove that an API feature is configured. Confirm the real request parameters and supported model in the application that will consume the response.
| Method | Main purpose | Still validate |
|---|---|---|
| Prompt alone | Describe fields and expected behavior | Syntax, structure, facts, and exceptions |
| JSON mode | Constrain valid JSON where supported | Fields, types, meaning, and response state |
| Schema-constrained output | Constrain supported structure | Source truth, business rules, refusal, and truncation |
4. Validate parsing, JSON Schema, and business rules
First, parse the returned content with a standard JSON parser to catch invalid quoting, trailing commas, and incomplete text. Second, validate required fields, types, enums, and extra properties. Third, check meaning: evidence must occur in the input, the category must follow your routing policy, and the review flag must agree with uncertainty. Record these results separately so a formatting improvement cannot hide a semantic regression.
The schema below matches the example fields and rejects additional properties. It does not prove that the summary is faithful or that the quoted words support the category. Your structured-output API may implement only a JSON Schema subset, so confirm compatibility before sending this definition directly. Keep a separate validator for application-side acceptance rather than assuming the API replaces every check.
{
"type": "object",
"properties": {
"category": {"type": "string", "enum": ["billing", "access", "other"]},
"summary": {"type": "string"},
"evidence": {"type": ["string", "null"]},
"needs_review": {"type": "boolean"}
},
"required": ["category", "summary", "evidence", "needs_review"],
"additionalProperties": false
}5. Handle truncation, refusal, and failed validation
Inspect the provider's completion status before parsing the body. A truncated object should not be repaired by guessing closing braces; reduce the output or retry within a sensible limit. Refusals may arrive through a separate response field and should not automatically enter the normal parser. Distinguish network errors, model refusal, invalid syntax, and business-rule failure in your records.
If you retry, provide the specific validation error, such as an enum value outside the allowed set, and cap the attempts. Preserve the original material and task. Do not fabricate a replacement fact just to satisfy a validator. When retries are exhausted, return an explicit failure or human-review state that the consumer understands instead of looping indefinitely.
Avoid broad regular-expression cleanup that deletes arbitrary text or inserts quotes until parsing succeeds. It can turn a refusal or explanation into a misleading object. Any preprocessing should have a narrow documented format, tests for its own behavior, and a visible record. Reliable extraction depends on detecting failure, not merely producing something that a parser accepts.
Test missing values and boundary cases explicitly
Use at least six input classes: a clear billing complaint, a clear login complaint, both intents together, an ambiguous complaint, quoted or multiline text, and an empty message. Reject the empty message before calling the model if that is your application rule. Do not manufacture a summary to make the absence of input look like a valid record.
For each case, record the expected category, review decision, acceptable evidence, and schema result. Decide in advance how to handle ‘this bill looks odd.’ If the team disagrees about its category, clarify the policy before changing the prompt. Model instructions cannot resolve a business definition that the product owner has not made.
Compare candidate prompts under the same model and request settings. Report valid-JSON rate separately from classification accuracy and evidence support. A correct category with a fabricated quote still fails its evidence requirement. Save the failing input as a regression case so the next format fix does not quietly reintroduce the same semantic error.
| Test input | category / needs_review | Acceptance check |
|---|---|---|
| I cannot log in. | access / false | Quote cannot log in from the source |
| I was charged twice and cannot log in. | other / true | Preserve both issues for manual routing |
| This is awful. | other / true | No category evidence; evidence is null |
| Empty or whitespace-only input | Do not call the model | Return an application input error |
Accept the data only after all three checks
Define the contract, choose the output constraint your interface actually supports, and validate syntax, shape, and meaning in sequence. Use the optimizer to clarify the instruction, then test it with your own parser and business rules. A complete-looking JSON prompt is a candidate for verification, not a guarantee that its output is safe to automate.
Recorded example: test the prompt contract
On 17 November 2026 we sent six synthetic English cases to DeepSeek Flash, once with an original instruction and once with a manually revised instruction. These are editorial rewrites, not outputs from the production optimizer. The two task groups cover JSON extraction and source-grounded refund rules, with complete, missing and conflicting facts.
This small, single-model run checks a predefined output contract. The revised prompt explicitly adds that contract, including null handling and raw JSON. Fenced JSON fails the raw-JSON check. Counts describe these cases only; they do not measure general accuracy, compare vendors, or establish the effectiveness of Prompt Optimizer, ChatGPT or Claude. Reruns may differ even at temperature zero.
DeepSeek Flash · 2026-11-17 · temperature: 0 · max_tokens: 700 · thinking: disabled · n = 1
JSON extraction
Original instruction
Extract order_id, amount, currency and status from the source. Return one JSON object with exactly those keys.Revised instruction
Extract order_id, amount, currency and status using only the source. Return one raw JSON object with exactly those keys, no prose or fences. order_id, currency and status are strings or null; amount is a number or null. Use null for missing or conflicting values. Do not choose one conflicting record without stated precedence. Do not infer currency, payment or zero amounts. Copy supported values without adding facts.| Case | Original passed | Revised passed |
|---|---|---|
| json-complete | Pass | Pass |
| json-missing | Pass | Pass |
| json-conflict | Fail | Pass |
Raw model output for the conflict case
Original instruction
{"order_id": "O-19", "amount": 10, "currency": "USD", "status": "paid"}Revised instruction
{"order_id":"O-19","amount":null,"currency":"USD","status":"paid"}Inputs, raw outputs, settings and checks (JSON) · Download the run and offline-verification script
Offline verification (no API key or network required)
node run-prompt-case-study.mjs --verify prompt-contract-20261117.jsonFrequently asked questions
Why does my JSON prompt still produce Markdown?
Natural-language instructions are not a strict format guarantee. Explicitly exclude fences, supply consistent examples, and use supported structured output where appropriate. Still check refusal, truncation, and parsing in your application.
Should an unknown number be zero or null?
Do not use zero if it can represent a genuine measured amount. Define null, omission, or a dedicated status in the contract and confirm the consumer handles it correctly.
Does passing JSON Schema validation prove the answer is correct?
No. Schema checks shape and supported value constraints. Verify source facts, quotations, category decisions, and cross-field business conditions separately.