Choose JSON Schema, Markdown, or plain text for AI output

The same AI answer has different risks when a person reads it and when software treats it as a record. A person can recognize that “last night” is imprecise; a parser may turn it into an exact timestamp. A heading can help a reader scan a note, yet code that assumes a particular heading position has acquired an undocumented interface. Before choosing JSON Schema, Markdown, or plain text, name the consumer, its next action, and the point where missing data must stop the handoff.

The prompt acceptance contract defines whether the answer’s content, evidence, and uncertainty meet the task’s standard. This page addresses the format of the handoff and the route for unusable or incomplete output. If the model proposes an external function call, its arguments and actual effects belong to a separate tool-calling contract. A user-facing response format cannot grant execution authority.

Start with the consumer, then select the format

Consumer and next step	Starting choice	Boundary to make explicit
Code, a database, or UI components consume several fields	Supported strict JSON Schema output	Field names, types, enums, unknown values, extra keys, version, and validation before use
A person reviews a sectioned explanation or checklist	Markdown	Headings and lists aid reading; code does not scrape business fields from their positions; use a configured renderer
Speech, SMS, or a one-line display carries a short message	Plain text	Length, terms, absolute times, and line breaks; validate exact values if the channel accepts only codes
Both software and people need the same facts	Structured facts plus a separate display layer	Software reads validated fields; presentation is rendered from those facts

This does not mean that Markdown cannot be parsed or that plain text can never be a protocol. A parser and a tiny, closed code vocabulary can both be valid choices. The danger is treating informal formatting as an unversioned data contract. Equally, a human-only note need not arrive wrapped in braces and quotation marks merely because an API can produce JSON.

JSON, JSON mode, and a strict schema promise different things

“Return JSON” in a prompt is a request. An API’s JSON mode constrains the result to JSON syntax but does not guarantee your required keys, types, or enum values. On supported models and endpoints, strict structured output further constrains the response to a specified subset of JSON Schema. Both OpenAI and Anthropic document subset limits and exceptions; do not assume every keyword in the full JSON Schema standard is enforced by your provider. OpenAI’s strict output requires an object at the root, all fields marked required, and additionalProperties: false on objects. A field that is unknown may be modeled as required but nullable. Some Anthropic SDK helpers transform constraints that the API itself does not support and then validate the original constraints locally. Changing helpers or calling the raw API changes what is actually enforced.

Record the provider, endpoint, model version, schema version, and date checked. Exercise the real integration with a normal input and an input missing a fact. Structural compliance still cannot tell you whether a place, date, citation, or decision is correct. That is a separate factual and business check.

Example one: a facility report enters a read-only review queue

A synthetic report says: “The escalator on the east building’s second floor stopped last night. The display showed E04. The reporter did not mention injuries.” The receiving system may put this information into a review queue. It may not dispatch a repair, close an incident, or infer anyone’s medical state. “Last night” is not an absolute date, so the model must not invent a precise timestamp to fill a field.

The following compact schema illustrates the shape. Check keyword support on the actual API and validate again in the application before using the result.

{
  "type": "object",
  "properties": {
    "location": { "type": "string" },
    "asset_type": { "type": "string", "enum": ["escalator", "other"] },
    "observed_at": { "type": ["string", "null"] },
    "error_code": { "type": ["string", "null"] },
    "injury_status": { "type": "string", "enum": ["reported", "explicitly_denied", "unknown"] }
  },
  "required": ["location", "asset_type", "observed_at", "error_code", "injury_status"],
  "additionalProperties": false
}

One acceptable candidate is {"location":"east building, second floor","asset_type":"escalator","observed_at":null,"error_code":"E04","injury_status":"unknown"}. Here null means the input does not supply a usable absolute time; unknown says that injury information is absent, not that no one was injured. The queue can ask a person for the missing facts without presenting an invented safety conclusion.

These four failures have different first gates. A provider-reported token limit or unfinished stream fails at the response boundary; only a provider-reported complete response with broken JSON is a syntax failure.

Response fragment	First failing layer	Route
Provider reports the output limit and text ends at {"location":"east building",	Response boundary	Reject the unfinished response; follow the explicit truncation route
Provider reports completion, yet text is {"location":"east building",	JSON syntax	Reject and log the parser error; bounded regeneration is only for output with no external effect
"injury_status":"none"	Schema enum	Reject and log the field path; do not silently coerce it to unknown
"observed_at":"last night", or an invented ISO timestamp	Business meaning	The first is not the agreed absolute time; the second has no source. Ask for the date before further use

The fourth row is why “it parses as JSON” is a weak gate. A string passes a basic type check while violating the rule that timestamps must be traceable and include a date and time zone. Stronger format constraints may help, but verify that the provider enforces the exact keyword you use. No schema can establish that the input actually supported the date.

Example two: a museum handoff has a web and a phone version

Another synthetic note says: “The west hall projector bulb was replaced; the interpretation label’s font remains unconfirmed; the director will review it at 10:00 on 4 October 2026 in Shanghai (UTC+08:00).” For a staff member reading a web page, Markdown can separate Completed, Unresolved, and Next review into headings and a short checklist. The page must apply its chosen Markdown rendering and HTML/link handling rules to untrusted text. Those headings are presentation, not a data source from which software should infer task status by position.

An SMS or spoken handoff works better as plain text: “The west hall projector bulb has been replaced. The label font still needs confirmation. The director will review it at 10:00 on 4 October 2026, Shanghai time.” The message has no Markdown marks and keeps the unresolved item, date, and time zone. If a work order also needs updating, first save validated structured facts, then render the web and phone versions from the same facts. Do not extract work-order fields back out of the display copy.

Check the response state before parsing complete content

Pass a generated response through the gates in this order:

1. Response boundary. Did the request succeed and the stream finish? Did the provider report refusal, a token limit, or another incomplete state? Even strict structured output may not match its schema after a refusal or truncation. Route a refusal through the permitted explanation or human path; do not evade it by changing wording. Never treat a partial JSON prefix as a finished record.
2. Syntax and structure. Parse only the completed JSON. Validate the schema version, required keys, types, enums, and unexpected keys. A streaming UI can show progress while buffering, but it must not commit an open object. Schema validation is essential for JSON mode, and exception states or provider, SDK, and model changes still need handling under strict mode.
3. Facts and business rules. Was the date present in the input? Are units and time zones consistent? Do citations refer to permitted evidence? Did unknown become “no”? Valid JSON can still fail these checks. The final action remains governed by the acceptance contract and executor permissions.

For generation tasks with no external effect, a bounded regeneration after a syntax or structure failure may be reasonable. Keep the original input and error type so the case can be retested. On repeated failure, clarify the input, use a previously tested fallback, or hand the case to a person. Do not silently “repair” a missing field with a regex or replace an invalid enum and present the result as the model’s answer. If a model call has already caused an uncertain external effect, check the authoritative state before replaying anything. The service fallback plan covers alternate model compatibility; the tool contract covers repeat effects.

Fill out an output protocol check

The workbench below can be edited, copied, and exported. Record the consumer, endpoint version, format choice, and field meanings. Then attach one valid example and four invalid ones: incomplete response, JSON syntax, schema, and business meaning. For each failure, specify where to block, whether a retry is allowed, the next permitted step, and the human owner. Test the same cases against the actual model and endpoint. Keep only sanitized case identifiers and invented examples in this browser’s local draft; do not paste customer text, credentials, or restricted logs.

A passing happy path is insufficient. Include a missing-date input, a refusal or truncation, a wrong type or enum, and a structurally valid but factually false result. Record the first failed layer. The answer-failure diagnosis helps decide whether to fix the schema, source input, validator, or later handoff.

Common questions

Do strict JSON Schema outputs still need local checks?

Handle refusals, truncation, interface differences, and business meaning. Which individual constraints are enforced depends on the provider’s supported subset, SDK helper, and model version; one provider’s promise does not transfer to another. At minimum, check response state and decision-changing facts, and define a route for anything the consumer cannot use.

Does one fixed label need JSON?

If the next step accepts only pass, review, or reject, a plain-text protocol with exact matching can be small. Once it needs a reason, evidence, and a next step, a versioned structured response is easier to maintain. Never let a similar word buried in open prose trigger an automatic action.

Boundary

This page designs the final response’s representation, validation, and parser-failure route. It does not prove that the answer is true or authorize a write. High-impact decisions still require source, identity, and human approval checks. When an external effect cannot be confirmed, reconcile its actual state before deciding whether to retry.