C
Claude Code Expert

Task 4.2

Structured Output

Structured output ensures Claude returns data in a predictable, parseable format — typically JSON. This is critical for applications that need to programmatically process Claude's responses.

JSON Output Techniques

There are several approaches to getting structured JSON output from Claude. The simplest is instruction-based: include 'Return your response as JSON' in the prompt with an example of the expected format. More reliable approaches use tool_use (define a tool with the desired output schema and have Claude 'call' it) or explicit JSON formatting instructions with schema definitions.

The tool_use approach is the most reliable because the model is trained to produce valid JSON for tool calls. By defining a 'report_result' tool with your desired schema, you guarantee structured output.

Schema Design for Model Output

When designing schemas for model output, prefer flat structures over deeply nested ones. Use descriptive field names that clearly indicate what information goes where. Include enum types for fields with a fixed set of values. Add field descriptions in the schema to guide the model.

Avoid schemas that require the model to make subjective judgments about where to place information. Clear, unambiguous field definitions produce more reliable output.

Validation and Error Recovery

Always validate structured output before using it. Check that JSON parses correctly, required fields are present, values are within expected ranges, and enum fields contain valid values.

When validation fails, you have options: retry with a more specific prompt, ask the model to fix its output by including the validation error, or use a default value. The retry-with-feedback approach is most effective — send the validation error back to the model so it can correct the issue.

Key Concept

Tool Use Is the Most Reliable Structured Output Method

Defining a 'result' tool with your desired JSON schema and having Claude call it is the most reliable way to get structured output. Claude is specifically trained to produce valid JSON for tool calls, making this approach more reliable than prompt-based JSON instructions. The tool call response includes the structured data as the tool's input parameters.

Exam Traps

EXAM TRAP

Relying on prompt instructions alone for JSON output

Prompt-based JSON instructions work most of the time but can produce malformed JSON or deviate from the expected schema. The tool_use approach is more reliable.

EXAM TRAP

Not validating structured output

Even with the best prompts, model output should always be validated before use. The exam expects you to know that validation is a required step.

EXAM TRAP

Using overly complex schemas

Deeply nested schemas with many optional fields increase the chance of malformed output. Simpler schemas are more reliable.

Check Your Understanding

You need Claude to extract product information from a description and return it as structured JSON with fields: name, price, category (one of: electronics, clothing, food), and features (array of strings). What is the most reliable approach?

Build Exercise

Implement Structured Output

Beginner30 minutes

What you'll learn

  • Get JSON output using the tool_use pattern
  • Design schemas for model output
  • Validate structured output
  • Handle validation failures with retry

  1. Define a tool schema for structured output (e.g., 'extract_info' with fields for name, date, and sentiment). Send a message to Claude with the tool and a text to analyze.

    WHY: The tool_use pattern is the most reliable way to get structured output from Claude.

    YOU SHOULD SEE: Claude calls the tool with correctly structured parameters.

  2. Parse the tool call result and validate it: check types, required fields, and value ranges.

    WHY: Even reliable structured output should be validated before use.

    YOU SHOULD SEE: Validation passes for well-formed output and catches malformed output.

  3. Handle a validation failure: when the output is malformed, send the error back to Claude and ask it to correct the output.

    WHY: Retry with feedback is the most effective recovery strategy for malformed structured output.

    YOU SHOULD SEE: Claude corrects the output based on the validation error.

  4. Compare reliability: test the same extraction 10 times with the tool_use approach vs. prompt-based JSON instructions. Count format errors for each.

    WHY: Empirical comparison demonstrates why tool_use is recommended over prompt-based JSON.

    YOU SHOULD SEE: Tool_use produces fewer format errors than prompt-based instructions.

Sources

Previous

System Prompts