Structured Output Prompts: JSON Schema Examples and Error-Handling Patterns for LLMs

Overview

Structured output prompting is the practice of directing a language model to return data in a predictable machine-readable format, usually JSON. It is useful when an AI application needs to pass model output to a database, API, workflow step, user interface, or validation layer.

A plain instruction such as Return JSON is not a complete reliability strategy. The model may add introductory text, omit a field, use the wrong data type, produce invalid JSON syntax, or return a value that is syntactically valid but unsuitable for your application. A stronger design combines four controls:

1. A precise schema: Define fields, types, allowed values, required properties, and nesting.
2. A focused prompt: Explain the task, source data, output contract, and handling of uncertainty.
3. Application-side validation: Parse and validate every response before using it.
4. A recovery path: Handle refusal, truncation, malformed JSON, timeouts, and validation failures without silently accepting bad data.

Use provider-native structured-output or schema-constrained features when they are available and appropriate, but treat them as one layer in the system rather than a substitute for validation. Feature names, SDK syntax, supported JSON Schema keywords, and model behavior can change, so verify implementation details against the documentation for the provider and model you are using.

A practical JSON Schema example

The following schema describes a support-ticket classifier. It uses required fields, an enum, a numeric range, and an array of nested objects.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account", "shipping", "other"],
      "description": "The primary category of the customer's request."
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "Urgency from 1 for low urgency to 5 for critical urgency."
    },
    "summary": {
      "type": "string",
      "description": "A factual summary in one sentence."
    },
    "missing_information": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Information needed before the request can be resolved."
    }
  },
  "required": ["category", "priority", "summary", "missing_information"]
}

additionalProperties: false can help prevent unexpected keys when the selected provider and schema mode support it. If a platform does not support a particular keyword, simplify the schema or enforce that rule in your application validator.

Checklist by scenario

When extracting fields from text

• Define each field with a specific description and expected type.
• State what to return when the source does not contain a value. Use null, an empty array, or a documented fallback consistently.
• Separate “not mentioned” from “false,” “zero,” or “unknown” where that distinction matters.
• Require the model to use only the supplied text if unsupported inference would create risk.
• Validate dates, identifiers, email addresses, and numeric ranges after parsing.

When classifying or routing requests

• Use an enum for categories instead of accepting unrestricted strings.
• Include an other or unclassified option when the input may fall outside known categories.
• Describe borderline cases in the prompt or provide a small set of representative examples.
• Return a confidence value only if your team has defined how it will be interpreted; a model-generated number is not automatically a calibrated probability.
• Keep the routing decision separate from any explanation needed for audit or debugging.

When generating nested objects

• Design the parent object first, then define each child object and array item.
• Make optional data explicit. A field can be optional at the schema level, or required but nullable; choose one deliberately.
• Limit nesting to what the consuming application actually needs.
• Specify whether arrays may be empty and whether item order has meaning.
• Test missing, repeated, contradictory, and unusually long inputs.

Reusable prompt template

System:
You are a data extraction component. Return only the structured object defined by the supplied schema.
Do not add Markdown, commentary, or keys that are not in the schema.
Use only the provided source text. If a value is not present, follow the schema's missing-value rule.

User:
Task: Extract the support-ticket fields from the source below.

Source text:
{{SOURCE_TEXT}}

Rules:
- Choose category only from the allowed enum values.
- Set priority from 1 to 5 using the definitions in the schema.
- Write a factual one-sentence summary.
- Add each unresolved information requirement to missing_information.
- Do not guess names, dates, amounts, or account details.

This template works best when the actual schema is supplied through the provider’s structured-output mechanism or included in a clearly delimited format. Keep task instructions separate from source text so user-provided content cannot easily overwrite the output contract.

When a provider offers structured-output modes

Compare the implementation options rather than assuming they are interchangeable:

What to double-check

Syntax is not semantics. A response can parse as JSON while still violating business rules. After parsing, run a schema validator and then apply domain checks. For example, confirm that a currency amount is non-negative, an identifier belongs to the expected format, and a category is permitted for the selected workflow.

Required and nullable are different. A required field must appear, but its value may be null if the schema allows it. An optional field may be absent. Choose based on what downstream code expects, and document the choice in the contract.

Descriptions influence consistency. “Priority” is ambiguous without a scale. Prefer descriptions such as “1 means informational; 5 means service-blocking and urgent.” Examples can clarify difficult boundaries, but they should not replace a formal schema.

Validate before side effects. Never send unvalidated model arguments directly to a database, payment operation, access-control change, email system, or external tool. Parse first, validate second, authorize third, and execute last.

Plan for malformed or incomplete output. A robust handler should distinguish at least these cases:

• Parse failure: The response is not valid JSON. Log a redacted sample and retry only when doing so is safe.
• Schema failure: JSON exists, but fields or types are wrong. Return a structured validation error to the retry step.
• Refusal or unsupported request: Do not force the result into the target schema. Route it to a refusal or human-review state.
• Truncation or timeout: Treat incomplete output as incomplete, not as a partial success, unless your application explicitly supports partial records.

A useful retry prompt includes the validator’s concise error, the original task, and the required schema. Avoid asking the model to “fix everything” without identifying the failure. Set a retry limit and record the final reason for failure.

Common mistakes

• Mixing JSON with commentary: Instructions such as “explain your reasoning, then return JSON” can make parsing brittle. Keep internal explanations out of the machine-readable response unless they are an intentional schema field.
• Using free-form labels: If downstream logic expects three categories, do not accept arbitrary labels and hope to normalize them later.
• Overloading one prompt: Extraction, policy decisions, summarization, and action selection may be easier to test as separate steps.
• Trusting a successful parse: Parsing confirms syntax, not truth, completeness, authorization, or business validity.
• Making every field required: This encourages guessed values when the source is incomplete. Represent uncertainty directly.
• Ignoring adversarial source text: Retrieved documents and user messages can contain instructions that conflict with your extraction task. Delimit source content and state which instructions have priority.
• Changing the schema without tests: Adding a field can affect prompts, validators, database mappings, UI code, analytics, and retries. Treat the schema as an interface.

For broader prompt design, test cases, and regression practices, pair this checklist with the LLM prompt testing framework and the guide to reliable prompt engineering frameworks.

When to revisit

Revisit structured-output prompts whenever the underlying contract changes. That includes adding or renaming fields, changing an enum, altering nullable behavior, migrating models, switching providers, changing SDK versions, or connecting a new downstream system. Provider feature support and schema limitations should be checked again after API changes rather than assumed to remain identical.

Before a seasonal planning cycle or a major workflow release, run a compact regression set containing normal inputs, empty inputs, missing fields, conflicting information, long inputs, non-English text if relevant, prompt-injection attempts, and examples near category boundaries. Compare parse success, schema validation, field completeness, and business-rule failures.

Use this final action checklist:

1. Write the smallest schema that meets the application’s needs.
2. Define missing-value behavior for every field.
3. Add descriptions, enums, ranges, and nested-object rules where they reduce ambiguity.
4. Select the strongest structured-output feature supported by your chosen model and verify its current limitations.
5. Validate syntax, schema, and domain rules in application code.
6. Separate retries from refusals, truncation, and human-review cases.
7. Test the prompt and schema together before deployment, then repeat those tests whenever the workflow or tools change.

Reliable LLM JSON is best treated as an interface-design problem. A clear contract, constrained prompt, defensive validator, and documented recovery path make structured output easier to maintain as your AI application evolves.