Reliable structured output starts with more than asking an LLM to “return JSON.” This guide provides adaptable prompts for JSON, CSV, and Markdown tables, a repeatable way to estimate output quality, and a validation checklist you can use in local tests or CI before changing models, schemas, or system prompts.
Overview
Structured-output prompts are instructions that constrain a model’s response to a format your application, spreadsheet, publishing workflow, or automation can consume. Common targets include JSON objects, CSV rows, and Markdown tables. Each format has a different failure surface: JSON may contain invalid syntax or unexpected fields, CSV may contain unescaped commas or line breaks, and tables may have inconsistent columns or explanatory text outside the table.
The most dependable approach combines four layers:
- A precise task: explain what information to extract, transform, or generate.
- A visible contract: define fields, types, allowed values, required fields, and handling for missing data.
- A response boundary: state exactly what may appear before and after the requested output.
- Programmatic validation: parse the result, check the schema, and record failures for regression testing.
Prompt wording improves consistency, but it does not replace validation. Treat every model response as untrusted input, even when the prompt is carefully designed. If your provider offers a native structured-output or schema-constrained mode, use it when it fits your workflow, then retain application-level validation for business rules and unexpected content.
For background on schema-based responses, see the structured output prompts guide. For broader formatting decisions, the AI prompt formatting guide explains when delimiters, Markdown, and examples are useful.
How to estimate structured-output reliability
Instead of judging a prompt from one successful response, estimate performance with a small, repeatable test set. The basic calculation is:
Pass rate = valid test cases ÷ total test cases × 100
Define “valid” before testing. A JSON response should parse, match the intended schema, and satisfy important business rules. A CSV response should have the expected header, the expected number of columns per row, and correctly escaped values. A Markdown table should contain one consistent header, the expected separator row, and the required columns without surrounding commentary.
A useful test record includes:
- the model or model version used;
- the system and user prompts;
- the input fixture;
- the expected structural properties;
- the raw response;
- the validation result and failure reason.
For example, run ten varied inputs rather than ten copies of one easy example. Include complete records, missing values, long text, punctuation, duplicate items, empty arrays, non-ASCII characters, and ambiguous wording. A prompt that passes simple examples but fails when a description contains a comma is not reliable enough for CSV production.
Track more than one score when the output matters. Separate syntax failures from schema failures and content-rule failures. This helps you choose the right fix: a syntax failure may require stricter output boundaries or a native response mode, while a business-rule failure may require a clearer definition or a downstream check.
Inputs and assumptions
Before writing a JSON schema prompt or choosing a format, document the assumptions that affect the result.
Choose the least fragile format
Use JSON when the output contains nested objects, arrays, typed fields, or optional values. Use CSV for flat, row-oriented data that will be imported into a spreadsheet or database. Use a Markdown table for human-readable summaries where strict machine parsing is secondary. If a table will be parsed automatically, JSON or CSV is usually a clearer contract.
Define missing and uncertain values
Do not leave null handling to implication. State whether missing information should be represented as null, an empty string, an empty array, or a fixed label such as unknown. Also tell the model not to infer values when the source does not support them.
Specify types and allowed values
Write down whether a field is a string, integer, number, Boolean, array, or object. For enumerations, list the permitted values exactly. If dates are required, choose one format and state whether a time zone is expected. These details reduce ambiguity and make validation straightforward.
Set a response boundary
Tell the model to return only the requested format and no greeting, explanation, Markdown fence, or trailing note. This instruction is especially important when your parser expects the first character to be { or the first row to be a CSV header. Do not ask for both a machine-readable response and a prose explanation in the same field unless the schema explicitly provides a place for it.
Template: JSON extraction prompt
System:
You return only valid JSON that matches the contract below.
Do not add Markdown fences, commentary, or extra keys.
Use null when a value is not present in the source. Do not guess.
Schema contract:
{
"title": "string",
"category": "one of: news, guide, review, other",
"summary": "string",
"tags": ["string"],
"source_url": "string or null"
}
User:
Extract the fields from the source text below.
Preserve the source meaning. Return one JSON object only.
SOURCE:
{{source_text}}Template: CSV prompt
Return CSV only. The first row must be this exact header:
id,title,category,summary
Return one row per item and no explanatory text.
Quote every field when needed, especially fields containing commas,
quotation marks, or line breaks. Escape an internal quotation mark
according to standard CSV rules. Use an empty field for missing values.
Do not create values that are not supported by the input.
INPUT:
{{items}}Template: Markdown table prompt
Return one Markdown table only with these columns, in this order:
| Name | Status | Owner | Next step |
Use one row per item. Keep each cell on one line. If a value is missing,
write "Not provided". Do not add an introduction, conclusion, bullet list,
or code fence outside the table.
INPUT:
{{records}}Worked examples
Example 1: validating a JSON response
Suppose an editorial workflow extracts metadata from an article. A successful response must parse as one object, contain exactly the required top-level fields, use one permitted category, and return an array for tags. A response such as {"title":"Guide","category":"guide","summary":"...","tags":[],"source_url":null} may pass structural validation. A response with "category":"tutorial" should fail if that value is not in the allowed set, even though the JSON syntax is valid.
Test at least these fixtures: a complete article, an article with no URL, text containing quotation marks, and text that does not clearly identify a category. The expected result for the last case should be the defined fallback, not a guessed category.
Example 2: validating CSV with punctuation
Use an input whose summary contains a comma, quotation mark, and line break. The output should still produce the expected number of columns after parsing with a real CSV parser. Do not validate CSV by simply splitting each line on commas; that approach misreads correctly quoted fields. Check the header exactly, parse the rows with a standards-aware library, and reject unexpected columns.
Example 3: validating a Markdown table
For a publishing dashboard, test an item whose next step contains a pipe character. The prompt should either require that character to be escaped or define a replacement. Then check that every data row has the same number of cells as the header. If the table is intended only for readers, visual review may be sufficient; if another program consumes it, convert the table to a structured representation and validate it before use.
Keep these cases in a small fixture file that can be rerun after prompt edits. The prompt testing framework and prompt evaluation playbook offer useful patterns for tracking test cases, failures, and revisions.
When to recalculate and update
Re-run the structured-output test set whenever you change the model, model version, system prompt, user prompt, schema, decoding settings, input preprocessing, or parser. Also retest after changing token limits or adding longer fields. Output behavior can differ across models and configurations, so a prompt that works in one environment should not be assumed portable. The cross-model prompt portability guide can help when comparing ChatGPT, Claude, and Gemini workflows.
As a maintenance rule, review the templates after each major model release or at least quarterly, whichever comes first. Update examples when output behavior, API capabilities, schema support, or parsing edge cases change. Record the previous pass rate, the new pass rate, and the exact failure categories; a single aggregate score can hide a serious regression in one field.
Before shipping a revised prompt, complete this checklist:
- Choose JSON, CSV, or Markdown based on how the output will be consumed.
- Define required fields, types, allowed values, and missing-value behavior.
- State that the response must contain only the requested format.
- Include representative examples and difficult edge cases in the test set.
- Parse the response with a real parser rather than string matching alone.
- Validate schema rules and application-level business rules separately.
- Log failures without silently repairing unknown or fabricated values.
- Re-run the same fixtures after every model or prompt change.
The practical goal is not a prompt that looks reliable in a demonstration. It is a prompt-and-validation workflow whose assumptions are visible, whose failures are measurable, and whose results can be compared whenever the underlying model or input conditions change.
