Output Format Control and Structured Outputs
Understand how to guide Claude to consistently produce parseable JSON outputs by writing precise system prompts, using assistant turn prefilling, and applying stop sequences. Learn to prevent common formatting errors that break parsers, ensuring your AI system can reliably extract structured data without complex preprocessing.
An agent that produces free-form prose is difficult to integrate with downstream systems. A pipeline that extracts fields from a response needs a predictable structure. A coordinator that reads specialist results needs JSON it can parse without a fragile regex. This lesson covers the techniques that move Claude from “usually returns JSON” to “always returns JSON.” By the end of this lesson, we will be able to:
Write system prompt instructions that consistently produce structured output
Use assistant turn prefilling to force a specific output opening
Use stop sequences to bound structured output without trailing commentary
Identify the three most common format failures and how to prevent each
Why “return JSON” in the system prompt is not enough
A system prompt instruction like “Return your answer as a JSON object” works most of the time. It fails in three specific situations:
Situation 1: Claude adds a preamble. Instead of starting with
{, Claude writes “Here is the JSON object you requested:” followed by the JSON. The response is valid if you strip the first line, but it breaks any parser that callsjson.loads()on the raw string.Situation 2: Claude wraps JSON in a markdown code block. Claude returns
```json\n{...}\n```instead of{...}. This is syntactically correct markdown but not directly parseable as JSON.Situation 3: Claude adds an explanation after the JSON. The JSON is valid but is followed by “Note: the
statusfield will be null if the order has not shipped yet.” The parser sees ...