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.

A JSON document passes separate parsing, schema, and business-rule checks.
Concept illustration: parseable JSON, the right structure, and correct business meaning need separate checks.
FieldType and valuesMissing-information behavior
categorybilling, access, or otherUse other when no category is established
summaryShort string based on the messageReject empty input before requesting a result
evidenceSource quote or nullUse null if no supporting quote exists
needs_reviewBooleanTrue 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.

MethodMain purposeStill validate
Prompt aloneDescribe fields and expected behaviorSyntax, structure, facts, and exceptions
JSON modeConstrain valid JSON where supportedFields, types, meaning, and response state
Schema-constrained outputConstrain supported structureSource 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 inputcategory / needs_reviewAcceptance check
I cannot log in.access / falseQuote cannot log in from the source
I was charged twice and cannot log in.other / truePreserve both issues for manual routing
This is awful.other / trueNo category evidence; evidence is null
Empty or whitespace-only inputDo not call the modelReturn 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.
CaseOriginal passedRevised passed
json-completePassPass
json-missingPassPass
json-conflictFailPass
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.json

Editorial method and corrections

Frequently 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.

Sources and further reading