json-mode-patterns

JSON Mode Patterns

Use native JSON outputs through output_config.format for a structured response. Use strict: true on a tool when its arguments need constrained decoding. Forcing a tool call alone does not guarantee schema compliance.

Native JSON response

This example uses the current Messages API shape. The caller supplies the approved model and output budget. Numeric limits are checked locally because raw structured output schemas do not support minimum and maximum.

import json
import math

ANALYSIS_SCHEMA = {
    "type": "object",
    "properties": {
        "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
        "confidence": {"type": "number"},
        "themes": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["sentiment", "confidence", "themes"],
    "additionalProperties": False,
}


def validate_analysis(result):
    if not isinstance(result, dict) or set(result) != set(ANALYSIS_SCHEMA["required"]):
        raise ValueError("Unexpected analysis fields")
    sentiment = result["sentiment"]
    if not isinstance(sentiment, str) or sentiment.casefold() not in {"positive", "neutral", "negative"}:
        raise ValueError("Unknown sentiment")
    confidence = result["confidence"]
    if (type(confidence) not in (int, float)
            or not 0 <= confidence <= 1 or not math.isfinite(confidence)):
        raise ValueError("Confidence must be finite and between zero and one")
    themes = result["themes"]
    if not isinstance(themes, list) or not 1 <= len(themes) <= 10 or not all(isinstance(t, str) for t in themes):
        raise ValueError("Expected one to ten theme strings")
    return {**result, "sentiment": sentiment.casefold()}


def analyze(client, model, text, max_tokens):
    response = client.messages.create(
        model=model,
        max_tokens=max_tokens,
        messages=[{"role": "user", "content": text}],
        output_config={"format": {"type": "json_schema", "schema": ANALYSIS_SCHEMA}},
    )
    if response.stop_reason != "end_turn":
        raise ValueError(f"Analysis incomplete: {response.stop_reason}")
    blocks = [block.text for block in response.content if block.type == "text"]
    if len(blocks) != 1:
        raise ValueError("Expected one structured response")
    return validate_analysis(json.loads(blocks[0]))