Study guide

3.1 Structured Outputs & JSON Extraction

Claude Certified Developer - Foundations CCDV-F

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Core Messages API & Streaming

1.1 Messages API Fundamentals & Request Lifecycle 1.2 Streaming & Server-Sent Events (SSE) 1.3 Thinking: Adaptive Mode, Effort & Reasoning Budgets

2 Chapter 2: Optimization & Asynchronous Batches

2.1 Prompt Caching Mechanics & Breakpoints 2.2 Message Batches API & Asynchronous Workloads

3 Chapter 3: Structured Outputs, Documents & Files API

3.1 Structured Outputs & JSON Extraction 3.2 Files API, Document Blocks & Citations

4 Chapter 4: Application Design, Resilience & Delivery Life Cycle

4.1 API Resilience, Error Handling & Retries 4.2 Production Backend Architecture & State Management 4.3 Requirements Analysis & Claude Application Design 4.4 The Claude Application Life Cycle & Configuration Management

5 Chapter 5: LLM Fundamentals, Model Selection & Versioning

5.1 LLM & Technical Fundamentals: Tokens, Context Windows & Sampling 5.2 Claude Model Family Selection 5.3 Model Versioning, Snapshot Pinning & Migration 5.4 Latency & Throughput Optimization

6 Chapter 6: Cost Engineering & Context Management

6.1 Production Cost Optimization Strategies 6.2 Context Window Management & Compaction

7 Chapter 7: Foundations of Workflows & Deterministic Patterns

7.1 Agent vs. Workflow Architectural Foundations 7.2 Workflow Patterns: Prompt Chaining & Routing 7.3 Workflow Patterns: Parallelization & Voting

8 Chapter 8: Autonomous Agents & Multi-Step Systems

8.1 Workflow Patterns: Orchestrator-Workers & Evaluator-Optimizer 8.2 Agent Loop Implementation & State Tracking 8.3 Agent Frameworks & Human-in-the-Loop (HITL)

9 Chapter 9: Prompt and Context Engineering

9.1 System Prompt Design & Role Framing 9.2 XML Tags & Structural Prompt Delimiters 9.3 Few-Shot Prompting & In-Context Learning 9.4 RAG Context Injection & Document Formatting

10 Chapter 10: Tool Calling & Model Context Protocol (MCP)

10.1 Tool Schema Design & Parameter Validation 10.2 Tool Execution, Multi-Tool Calls & Error Handling 10.3 MCP Architecture & Core Primitives 10.4 MCP Transports & Client/Server Integration 10.5 Agentic Customization: Built-in Tools, Custom Tools, Skills & MCP

11 Chapter 11: Security, Safety & Governance

11.1 Direct & Indirect Prompt Injection Defenses 11.2 Tool Permissions, Sandboxing & Least Privilege 11.3 Data Privacy, Redaction & Audit Logging 11.4 Identity, Secrets & API Key Management

12 Chapter 12: Claude Code Developer Tooling

12.1 Claude Code Architecture & Project Configuration 12.2 Permissions, Modes & Hooks

13 Chapter 13: Evaluation, Testing & Production Observability

13.1 Evaluation Design & Golden Datasets 13.2 Production Observability, Tracing & Debugging

3.1 Structured Outputs & JSON Extraction

Key Takeaways Explain This Topic AI

Structured outputs ( output_config.format ) and strict tool use ( strict: true ) are the mechanisms that guarantee schema-valid JSON from Claude; on Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5 a forced tool_choice ( any or tool ) returns a 400 error, so use auto with strict tools or structured outputs instead.

Prompt-enforced JSON cannot guarantee type safety and prevents neither schema hallucination nor key drift, and assistant prefill ( { ) returns a 400 error on Claude 4.6 and later models.

The SDKs' messages.parse() helper sends a Pydantic model (Python) or Zod schema (TypeScript) as output_config.format , validates the response, and returns the typed result; a plain tool_use.input arrives already parsed into a dictionary or object that you validate yourself.

Two-phase validation cleanly separates syntactic schema conformance from domain business rules, allowing failed business validations to be repaired using multi-turn error loops with tool_result where is_error: true .

Extracting large structured records requires allocating sufficient max_tokens ; hitting token limits results in stop_reason: "max_tokens" and abruptly truncated, unparseable JSON.

Last updated: October 2026

The Structured Data Imperative in LLM Architectures

Modern enterprise applications rarely consume raw, conversational natural language in isolation. Production architectures—ranging from robotic process automation (RPA) workflows and database synchronization pipelines to microservice communication and autonomous agent state machines—demand deterministic, machine-readable structured payloads . When integrating Large Language Models (LLMs) like Claude into backend services, developers must guarantee that extracted records adhere strictly to typed schema contracts, typically represented as JSON.

Historically, developers relied on two primary prompting conventions to extract JSON from language models, each introducing acute operational fragility:

Prompt-Enforced JSON : The developer instructs Claude via system or user prompts to "respond strictly in valid JSON matching the following schema" . While Claude possesses strong instruction-following capabilities, prompt-based extraction presents persistent non-deterministic failure modes:

Conversational Preamble and Postamble : The model frequently emits polite conversational wrappers (e.g., "Certainly! Here is the extracted JSON payload:" ) or trailing clarifications ( "Note: Some fields were estimated based on document context." ). These extraneous tokens break standard JSON deserializers such as Python's json.loads() or JavaScript's JSON.parse() .

Markdown Code Fence Enclosure : Models routinely wrap payloads in markdown code fences ( json ... ). While regex strip utilities can remove backticks, variations such as missing closing fences, arbitrary whitespace, or nested code blocks degrade parser reliability.

Schema Hallucination and Key Drift : Under heavy context or ambiguous inputs, prompted models may rename properties, hallucinate undocumented attributes, or alter primitive types (e.g., emitting a string "1200" instead of an integer 1200 ).

Assistant Role Prefilling (retired) : On earlier models, developers supplied an initial token prefix in the assistant message turn (such as { ) so Claude continued directly from it, which suppressed preambles. Prefilling is not supported on Claude 4.6 and later models: the request returns a 400 error. Even where it still works, prefill was inadequate for enterprise workloads:

It provides no structural or syntactic constraints on tokens generated after the opening brace.

It cannot enforce parameter types, mandatory field lists, or nested object relationships.

It cannot be easily unified with function calling pipelines or multi-agent orchestration frameworks.

Schema-Constrained Output: Structured Outputs and Strict Tool Use

To overcome the non-determinism of prompt-based approaches, Anthropic provides structured outputs , which come in two complementary features that can be used separately or together:

JSON outputs ( output_config.format ) : Claude's response itself follows a JSON Schema you supply. This is the direct tool for extraction: the JSON arrives in the response's text content block.

Strict tool use ( strict: true on a tool definition) : the tool name and the input Claude generates are guaranteed to validate against the tool's input_schema (which must set additionalProperties: false and list its required fields).

Under either feature:

Schema Enforcement by Construction : generation is constrained to the supplied JSON Schema, so mismatched braces, undeclared properties, and invalid enum values cannot appear. Without structured outputs, Claude usually follows a tool's schema but can still produce malformed JSON or invalid tool inputs, so ordinary tool calling needs validation in code.

Type Safety : the model is held to the declared primitive types ( string , number , integer , boolean ), composite types ( array , object ), and enum values. Some JSON Schema constraints, such as minimum and maxLength , are not supported by the API; the SDK helpers move them into the field description and check them on the response.

Client Parsing : client.messages.parse() validates the response against your Pydantic or Zod schema and returns it in parsed_output ; a tool_use block's input is already a native dictionary or object. +-------------------------------------------------------------------------+

  • | The Extraction Spectrum |
  • +-------------------------------------------------------------------------+
  • | Prompting Only Assistant Prefill ({) Structured Outputs |
  • | ----------------- --------------------- --------------------- |
  • | - Markdown fences - 400 error on Claude - Zero preamble |
  • | - Conversational chatter 4.6 and later models - Schema constrained |
  • | - Fragile regex - Unconstrained schema - Typed SDK objects |
  • | - Low reliability - Legacy models only - Enterprise standard |
  • +-------------------------------------------------------------------------+
  • tool_choice and Forced Tool Use

In standard conversational workflows, Claude autonomously decides whether to answer with conversational text or call an available tool. Older extraction pipelines forced a specific tool so Claude always produced the extraction call. Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5 reject forced tool use: tool_choice of any or tool returns a 400 error. On those models, use structured outputs when you need a response in a fixed JSON shape, or auto with a strict tool and a prompt instruction naming the tool. Models such as Claude Haiku 5.5 and the legacy Claude Opus 5 still accept forced tool use.

The tool_choice parameter has these modes (plus {"type": "none"} , which prevents tool calls):

{"type": "auto"} (Default): Claude evaluates the conversation and decides autonomously whether to reply with conversational text or invoke one or more tools from the tools array.

{"type": "any"} : Claude is strictly forced to invoke at least one tool from the provided tools list, but retains autonomy regarding which specific tool to call.

{"type": "tool", "name": "<tool_name>"} : Claude is deterministically forced to invoke the exact named tool specified in the object.

On a model that accepts forced tool use, specifying tool_choice: {"type": "tool", "name": "extract_entity"} suppresses conversational text blocks entirely (and skips thinking). The API response then contains:

stop_reason : Set explicitly to "tool_use" upon successful completion.

content : Contains a tool_use content block with the generated tool invocation id , the tool name , and the parsed structured input object conforming to your schema.

  • API Request Structure (structured outputs) {
  • "model": "claude-sonnet-5-5",
  • "max_tokens": 2048,
  • "output_config": {
  • "format": {
  • "type": "json_schema",
  • "schema": {
  • "type": "object",
  • "properties": {
  • "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
  • "vendor_name": {"type": "string", "description": "Legal corporate name of vendor"},
  • "issue_date": {"type": "string", "description": "ISO 8601 date string (YYYY-MM-DD)"},
  • "total_amount": {"type": "number", "description": "Gross invoice balance due"},
  • "currency": {"type": "string", "enum": ["USD", "EUR", "GBP", "CAD"]},
  • "line_items": {
  • "type": "array",
  • "items": {
  • "type": "object",
  • "properties": {
  • "description": {"type": "string"},
  • "quantity": {"type": "integer", "description": "At least 1"},
  • "unit_price": {"type": "number", "description": "Zero or more"}
  • },
  • "required": ["description", "quantity", "unit_price"],
  • "additionalProperties": false
  • }
  • }
  • },
  • "required": ["invoice_id", "vendor_name", "issue_date", "total_amount", "currency", "line_items"],
  • "additionalProperties": false
  • }
  • }
  • },
  • "messages": [
  • {
  • "role": "user",

"content": "Invoice INV-5541 from Nexus Cloud Inc., issued 2026-07-15. Items: 4 Compute Clusters at $800 each ($3,200) and 1 Managed VPC at $450. Total balance: $3,650.00 USD."

  • }
  • ]
  • }
  • Integration with Validation Frameworks: Pydantic & Zod

In modern production codebases, maintaining raw JSON Schema dictionaries as static strings is error-prone. Industry best practice establishes type-safe models using Pydantic in Python or Zod in TypeScript as the single source of truth. The SDK's messages.parse() helper converts the model into output_config.format , validates Claude's response against it, and returns the typed result in parsed_output .

  • Python Implementation with Pydantic v2 from typing import List, Literal
  • from pydantic import BaseModel, Field
  • import anthropic

# 1. Define schema contracts with Pydantic models

class LineItem(BaseModel):

  • description: str = Field(description="Itemized product or service name")
  • quantity: int = Field(ge=1, description="Number of units ordered")
  • unit_price: float = Field(ge=0.0, description="Price per unit in designated currency")

class InvoiceExtraction(BaseModel):

  • invoice_id: str = Field(description="Unique alphanumeric invoice identifier")
  • vendor_name: str = Field(description="Legal name of the issuing vendor")
  • issue_date: str = Field(description="Date of invoice issuance in YYYY-MM-DD format")
  • total_amount: float = Field(ge=0.0, description="Total billed amount inclusive of tax")
  • currency: Literal["USD", "EUR", "GBP", "CAD"] = Field(description="ISO currency code")
  • line_items: List[LineItem] = Field(description="Itemized breakdown of purchased goods")
  • # 2. Pass the model to messages.parse(); the SDK sends it as output_config.format
  • client = anthropic.Anthropic()
  • # 3. Dispatch the extraction request with structured outputs
  • response = client.messages.parse(
  • model="claude-sonnet-5-5",
  • max_tokens=2048,
  • output_format=InvoiceExtraction,
  • messages=[
  • {
  • "role": "user",

"content": "Invoice INV-9812 issued by Datacenter Systems on 2026-08-01: 2 Backup Arrays at $1500 each. Total: $3000 USD."

  • }
  • ]
  • )

# 4. Check stop_reason, then read the validated model

if response.stop_reason == "max_tokens":

  • raise RuntimeError("Output truncated: raise max_tokens or chunk the input")
  • invoice: InvoiceExtraction = response.parsed_output
  • print(f"Successfully extracted invoice {invoice.invoice_id} for ${invoice.total_amount}")
  • TypeScript Implementation with Zod import Anthropic from "@anthropic-ai/sdk";
  • import { z } from "zod";
  • import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
  • // 1. Define contract using Zod schema
  • const LineItemSchema = z.object({
  • description: z.string().describe("Itemized description"),
  • quantity: z.number().int().positive().describe("Item quantity"),
  • unit_price: z.number().nonnegative().describe("Unit cost"),
  • });
  • const InvoiceSchema = z.object({
  • invoice_id: z.string().describe("Alphanumeric invoice code"),
  • vendor_name: z.string().describe("Merchant legal name"),
  • issue_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("ISO date YYYY-MM-DD"),
  • total_amount: z.number().nonnegative().describe("Final invoice total"),
  • currency: z.enum(["USD", "EUR", "GBP", "CAD"]).describe("Currency code"),
  • line_items: z.array(LineItemSchema).describe("Itemized line list"),
  • });

type Invoice = z.infer<typeof InvoiceSchema>;

  • // 2. Wrap the Zod schema with zodOutputFormat() for structured outputs
  • const client = new Anthropic();
  • const response = await client.messages.parse({
  • model: "claude-sonnet-5-5",
  • max_tokens: 2048,
  • output_config: { format: zodOutputFormat(InvoiceSchema) },
  • messages: [
  • {
  • role: "user",

content: "Invoice INV-404 from Global CDN Corp, date 2026-09-01. Total $900 USD. 1 Edge Routing node at $900.",

  • },
  • ],
  • });
  • // 3. Check stop_reason, then read the validated result
  • if (response.stop_reason === "max_tokens") {
  • throw new Error("Output truncated: raise max_tokens or chunk the input");
  • }
  • const validatedData: Invoice = response.parsed_output!;
  • console.log(`Validated Invoice ID: ${validatedData.invoice_id}`);
  • Handling Extraction Edge Cases & Production Resilience

Even with schema-constrained decoding, real-world data pipelines must account for edge cases and unexpected inputs.

Nullability and Missing Properties

JSON Schema distinguishes between optional properties and nullable properties:

Optional Properties : Omitted from the required array. Claude may choose not to emit the key if the corresponding information is absent from the source document.

Nullable Properties : Explicitly permit null as a valid type (e.g., "type": ["string", "null"] ). In Pydantic, define these as Optional[str] = None .

Best Practice : Never assume optional fields will default to empty strings or zeroes. Always annotate models with clear fallback defaults or inspect dictionary keys using safe .get() accessors.

Token Budget Exhaustion ( stop_reason: "max_tokens" )

When extracting records from long, information-dense documents, the generated JSON string may exceed the request's configured max_tokens . When this occurs:

Claude abruptly ceases generation mid-payload.

stop_reason is set to "max_tokens" (rather than "end_turn" or "tool_use" ).

The JSON payload is truncated, missing terminating quotes, commas, or closing brackets, rendering it syntactically invalid even with structured outputs.

Production Rule : Always inspect response.stop_reason . If stop_reason === "max_tokens" , do not attempt to parse the truncated output. Log an alert, dynamically increase max_tokens , or segment the source text into smaller extraction chunks.

Two-Phase Validation and Multi-Turn Error Recovery

In enterprise systems, data validation operates across two distinct layers:

Phase 1: Syntactic Validation : Ensures the JSON payload adheres to property types, array boundaries, and regex formats (handled by JSON Schema and Pydantic/Zod).

Phase 2: Semantic Business Validation : Evaluates cross-field domain logic that static schemas cannot capture—such as checking whether sum(item.quantity * item.unit_price) == total_amount , or verifying that end_date >= start_date .

When Phase 2 business logic fails, robust architectures implement an Error Feedback Loop using standard tool-use semantics:

The application retains the assistant's tool_use message in conversation history.

The application appends a user turn containing a tool_result content block referencing tool_use_id: tool_block.id , setting is_error: true , and providing the diagnostic validation message.

The application re-invokes the Messages API (with tool_choice left at auto on models that reject forced tool use). Claude inspects the validation error, re-evaluates the source text, and generates a corrected tool call.

Comparison of Structured Extraction Techniques

  • Architectural Attribute Structured Outputs / Strict Tool Use Prompting with XML / Tags Assistant Prefill ( { )
  • Availability Current models All models Returns a 400 error on Claude 4.6 and later models

Schema Enforcement JSON Schema enforced during generation Heuristic; relies solely on prompt compliance Loose; enforces initial bracket only

Preamble / Postamble Risk Zero; eliminated by construction High; emits conversational wrappers Low on legacy models; continues after prefix

Data Type Safety Strict enforcement of numbers, booleans, enums Poor; frequently coerces numbers to strings Weak; no control over nested types

Client SDK Parsing messages.parse() returns a validated typed object Requires custom regex and manual JSON parse Requires manual json.loads or JSON.parse

Error Recovery Flow Standard tool_result with is_error: true for tools; re-prompt for JSON outputs Natural language re-prompting Append correction text to conversation

Token Overhead Schema consumes context tokens Schema described in prompt text Minimal input overhead; high risk of drift

Common CCDV-F Exam Traps & Pitfalls

Forcing tools on models that reject it : tool_choice of any or tool returns a 400 error on Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5.

Accessing response.content[0].text on Tool Calls : When Claude calls a tool, it emits a tool_use content block, not a text block. Code attempting to read .text will throw an attribute error or return undefined .

Double-Parsing SDK Output : In official Anthropic SDKs (Python and TypeScript), tool_block.input is already parsed into a native dictionary or object. Calling json.loads(tool_block.input) in Python causes a runtime TypeError .

Omitting Field Descriptions : Relying on bare property names without providing description attributes in JSON Schema. Claude heavily utilizes field descriptions to understand semantic extraction rules, expected date formats, and domain nuances.

Failing to Guard Against max_tokens : Assuming HTTP status 200 guarantees a complete extraction. If stop_reason is "max_tokens" , the JSON payload is truncated and malformed.

Loading diagram... Two-Phase Structured Output Validation & Self-Correction Loop