Getting Structured Output — JSON, Markdown, and More

Series: Claude Learning Journey · Core Workflows

Prose is for humans. Programs need structured data. Claude can produce both, but the difference between a useful output and a messy one is often a matter of how specifically you ask for the format you need. If you want JSON, say JSON. If you want a table, say table. The model responds to clear format specifications.

Why structured output matters

When Claude outputs unstructured prose, you have to read and parse it yourself. When it outputs structured data, you can pipe it directly into the next step of a pipeline.

# Unstructured — requires reading and manual extraction
Claude: "The three most expensive operations are: (1) the database query on line 42 which does a full table scan, (2) the image resizing on line 78 which loads the full-resolution image into memory, and (3) the third-party API call on line 95 which waits synchronously for a response."

# Structured — can be used directly
Claude: "[{"operation": "db_query", "file": "handlers.py", "line": 42, "issue": "full_table_scan"}, {"operation": "image_resize", "file": "thumbnail.py", "line": 78, "issue": "memory_bloat"}, {"operation": "api_call", "file": "client.py", "line": 95, "issue": "sync_blocking"}]"

The JSON version is machine-readable. You can parse it, filter it, display it in a UI, or use it to drive automated fixes.

Requesting JSON

Be explicit about the JSON structure you want:

You: "Analyse this function and return a JSON object with this structure:
{
  "complexity_score": 0-10,
  "issues": [{"type": "string", "severity": "high|medium|low", "description": "string", "line": number}],
  "suggestions": ["string"]
}
Only return valid JSON. Do not include any explanatory text before or after."

Claude will respect format constraints if they are clear. The key instructions are:

• Describe the exact structure
• Say “only return valid JSON”
• Say “no explanatory text”
• Specify the schema explicitly

Markdown tables

For comparison, classification, and analysis tasks, markdown tables are often clearer than prose:

You: "Compare these three caching approaches. Return a markdown table with columns: Approach, Best For, Latency, Cache Invalidation Complexity."

Markdown tables render nicely in any client and are easy to parse programmatically.

Code as output

If you want code, specify the language and format:

You: "Write a Python function that takes a list of ISO date strings and returns them sorted oldest first. Return only the function — no explanation, no test code."

Specify what you do not want as well as what you do. “No explanation, no test code” prevents the usually helpful but sometimes unwanted extra content.

YAML and other formats

Claude can output YAML, TOML, XML, and other structured formats. The same principle applies: describe the exact format you want, including indentation expectations if they matter.

YAML is particularly useful for configuration because it maps directly to most config parsers:

You: "Generate a Kubernetes deployment YAML for this Docker image. Include resource limits, a readiness probe, and environment variables from a ConfigMap. Only output the YAML."

Streaming output

For long outputs, streaming is useful but makes structured parsing harder since you do not have the complete JSON until the stream finishes. If you need to parse structured data from a streaming response, wait for completion before parsing.

In the CLI:

claude --agent "refactor all the functions in this file and return a JSON summary of what changed"

The response will stream, but the final structured output is available once complete.

Handling Claude’s tendency to add context

Claude sometimes prepends or appends explanatory text to structured output. Counter this by being explicit:

You: "Return ONLY the JSON array. No markdown fences, no backticks, no labels, no text before or after. Just the raw JSON."

If Claude persists in adding text, ask it to regenerate with a tighter constraint, or strip the non-JSON lines programmatically.

When prose is better

Not everything needs to be structured. Sometimes a natural language explanation is more useful than a JSON object. The point is to choose deliberately based on how the output will be used:

• Will a human read it? Prose or markdown is fine
• Will a program read it? JSON or a machine-readable format
• Will it be rendered in a UI? Markdown tables or structured data with UI hints

Try it yourself

Ask Claude the same question three times, requesting different formats: unstructured prose, a markdown table, and JSON. Compare the three outputs. Which is most useful depends entirely on what you need it for.

What’s Next

Stage 2 complete. Stage 3 moves from core workflows to intermediate engineering skills — setting up projects, writing tests, and working with the kind of real codebases that have ambiguity, legacy sections, and multiple contributors.

Part of the Claude Learning Journey series · Next: Setting Up a New Project with Claude