Claude API の構造化出力（Structured outputs）の使い方

構造化出力（Structured outputs）は、Claude の応答を指定したスキーマに必ず従わせる機能です。JSON のパース失敗やスキーマ違反による再試行をなくし、出力をそのまま後続処理に流せるようにします。

構造化出力とは

構造化出力には 2 つの機能があります。

JSON 出力（output_config.format）— Claude のテキスト応答そのものを、指定した JSON スキーマに従わせる。メールや請求書からのデータ抽出、感情分析やカテゴリ分類、API レスポンス形式への整形などに使う。
strict ツール使用（ツール定義の strict: true）— ツール名と入力パラメータがスキーマどおりであることを保証する。

Claude API では一般提供されており、Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Opus 4.7 / 4.6 / 4.5、Claude Sonnet 5 / 4.6 / 4.5、Claude Haiku 4.5 で利用できます。Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry でも各プラットフォームの対応モデルで使えます。

JSON出力の設定

JSON 出力は output_config の format に json_schema 型のスキーマを渡して有効にします。

output_config={
    "format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string"}
            },
            "required": ["name", "email"],
            "additionalProperties": False
        }
    }
}

この設定を付けると、応答テキストはスキーマを満たす JSON になります。抽出したいフィールドを required に入れ、想定外のキーが混ざらないよう additionalProperties を false にしておくのが基本形です。

strictツール使用

ツール入力側を厳密にしたい場合は、ツール定義に strict: true を付けます。

tools=[
    {
        "name": "search_flights",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "destination": {"type": "string"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["destination", "date"],
            "additionalProperties": False
        }
    }
]

これにより、ツール呼び出しの input がスキーマから外れることがなくなり、受け取り側でのバリデーションと再試行の実装を減らせます。

対応するスキーマ機能

サポートされるスキーマ機能は次のとおりです。

基本型（object / array / string / integer / number / boolean / null）
enum、const、anyOf、allOf
$ref、$def、definitions
文字列フォーマット（date-time、time、date、email、uri、uuid など）
配列制約のうち minItems（値は 0 または 1 のみ）

一方、次はサポートされません。

再帰的なスキーマ
minimum / maximum などの数値制約
minLength / maxLength などの文字列制約
複雑な配列制約
additionalProperties に false 以外を指定すること
外部 $ref

制限と注意点

スキーマの複雑さには上限があります。1 リクエストあたりの strict ツールは 20 個まで、オプションパラメータの総数は 24 個まで、union 型を使うパラメータは 16 個までです。

性能面では、初回リクエストでスキーマをグラマーにコンパイルするぶんレイテンシが増えますが、コンパイル結果は 24 時間キャッシュされます。JSON スキーマの構造を変えたり、ツールセットを変更したりするとキャッシュは無効化されます。

出力に関する注意点は次のとおりです。

プロパティの順序は、必須プロパティが先、オプションが後になる
安全上の理由で Claude が拒否した場合（stop_reason: "refusal"）は、スキーマに従わない拒否メッセージが返る
トークン上限に達した場合（stop_reason: "max_tokens"）は出力が不完全になりうる
enum 値の大文字小文字は保証されないため、比較は大文字小文字を区別せずに行う

SDKのサポート

主要な SDK では、言語ネイティブの型定義からスキーマを生成できます。

Python — Pydantic モデル＋ client.messages.parse()
TypeScript — Zod スキーマ＋ zodOutputFormat()、または JSON Schema リテラル
Java — Java クラス＋ outputConfig(Class<T>)
Ruby — Anthropic::BaseModel のサブクラス
PHP — StructuredOutputModel インターフェースの実装クラス
C# — ジェネリックの Create<T>() オーバーロード
Go — Go の構造体（リフレクションでスキーマを生成）

スキーマを 2 箇所（コードと JSON）で二重管理せずに済むため、実装では SDK のネイティブ定義を使うのが扱いやすい方法です。

次に読むもの

構造化出力と関係の深いトピックは次のとおりです。

ツール使用 — strict ツール使用の前提となる tools の基本
プロンプトキャッシュ — スキーマのコンパイルキャッシュとは別に、プロンプト側のキャッシュでコストを下げる
メッセージバッチ — 大量の抽出・分類処理をまとめて流す

本記事は Anthropic 公式ドキュメントの Structured outputs ページ（2026年7月19日時点）に基づく非公式の日本語解説です。対応モデルや制限は更新される場合があるため、実装前に公式ドキュメントで最新をご確認ください。