json-mode-patterns

JSON Mode Patterns

Claude does not have a dedicated response_format: json parameter like some other APIs. The idiomatic way to get guaranteed JSON is tool use with a forced function call. This skill documents that pattern plus fallbacks.

Preferred Pattern: Tool-as-Schema

Define a tool whose input schema IS the JSON shape you want, then force the model to call it.

tools = [{
    "name": "record_analysis",
    "description": "Return the analysis as structured data",
    "input_schema": {
        "type": "object",
        "properties": {
            "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
            "confidence": {"type": "number", "minimum": 0, "maximum": 1},
            "themes": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["sentiment", "confidence", "themes"]
    }
}]

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "record_analysis"},
    messages=[{"role": "user", "content": text_to_analyze}]
)

# The structured result is in response.content
for block in response.content:
    if block.type == "tool_use" and block.name == "record_analysis":
        result = block.input  # already a Python dict, schema-validated
        break

Why this wins:

• Schema is enforced at the API level
• No regex or parsing from model text
• Enums, min/max, required fields actually constrain the output

Fallback: Prompted JSON + Strict Parse

When tool use is unavailable (some SDKs/proxies strip it):

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="You return ONLY valid JSON. No prose, no markdown fences.",
    messages=[{
        "role": "user",
        "content": f"Extract as JSON matching this schema: {schema_str}\n\nInput: {text}"
    }]
)

import json
try:
    result = json.loads(response.content[0].text)
except json.JSONDecodeError:
    # Claude sometimes wraps in ```json ... ```
    result = json.loads(strip_markdown_fence(response.content[0].text))