LLM 構造化出力の失敗:strict モードの Schema はこう書き直す
要点:普通の JSON Schema にいきなり strict を付けると 400 が返る:全フィールド必須、全オブジェクトで additionalProperties を封印、$ref と allOf は拒否。本記事では供給側の制約に沿って緩い schema を strict 対応版へ一括改写し、null 許容ユニオン・ハードリミット・refusal 振り分けのチェックリストを提示する。

結論:strict: true は「もう少し丁寧に」というスイッチではなく、JSON Schema のサブセットしか受け付けない契約である。全フィールド必須、全オブジェクトで additionalProperties の封印、$ref と allOf は即拒否。書き直さないまま strict を付けると、より信頼できる出力ではなく 400 が返ってくる。
同じ schema でも、ローカルのバリデータでは問題なく通るのに、strict: true を付けてモデル API に送るとそのまま返送される。モデルが賢くなくなったのではなく、供給側が「制約付きデコード」に必要な schema サブセットにハードな境界線を引いたのだ。あなたの schema がその線を越えた。
一、strict は何を変えるのか:サンプラーを文法に鎖でつなぐ
通常モードでは、モデルの生成する JSON はあなたの schema に「たぶん」合致するだけで、prompt の「JSON を出力してください」という一文に頼って後始末する。OpenAI 公式の evals では、gpt-4-0613 がプロンプトだけでの複雑 schema 遵循率は 40% 未満。strict を付けると、gpt-4o-2024-08-06 が同じ評価セットで 100% を達成した。
仕組みは制約付きデコード(constrained decoding)だ。API は最初のリクエストであなたの schema を有限状態機械にコンパイルし、デコード段階ではすべての token が状態機械の通行許可を得る。schema に反する token はモデルが「発行できない」。これは注意を促すものではなく、物理的に鍵をかける行为だ。代償は二つ:新しい schema の初回コンパイルに追加時間がかかり(典型的には 10 秒以内、複雑な schema では 1 分に達する)、最初の token に 5〜8% の遅延が増える。コンパイル产物はキャッシュされ、以降のリクエストは追加コストを払わない。
ただし何を保証し何を保証しないかを明確に:文法と形状は鎖でつながれるが、意味論はそうではない。モデルは estimate_hours に 400 を自信満々に埋め込み、間違ったメールアドレスを抽出することもできる。形状は床であって天井ではない。意味の品質は評価セットで守るしかない。2026 年の最先端モデルでも負荷下では約 0.4% の破形率が残るため、リトライループは依然として必須だ。
二、三つの硬いルール:全必須・余計な鍵の封印・null 許容
strict モードが schema に課す改写要件は三つだけだが、どれも通常の schema の書き方の直感と正反対である:
- 全フィールドを required に書き込む。 strict はオプションフィールドという概念を受け付けない。「任意」を表現したいなら、フィールドを required に残したまま型を null 許容ユニオン
"type": ["string", "null"]にし、欠落時はモデルに null を返させる。これは required に本当に必要なフィールドだけを列挙する一般的な JSON Schema の実践と完全に逆だ。 - 全オブジェクトで additionalProperties: false を明示する。 通常の実践ではこれを設定しないことが多い(本サイトの additionalProperties の三つのランタイム挙動の記事を参照)。しかし strict モードではこれは准入条件であり、書かなければエラーになる。理由は単純だ。状態機械は宣言された鍵しか生成できず、宣言外の鍵は文法上そもそも到達不可能だからだ。
- Python ユーザーの罠:Pydantic はデフォルト値つきのフィールドを required から落とす。
priority: str = "low"と書くだけで、生成された schema の required が一项欠け、strict は即拒否する。デフォルト値を外すか、下のスクリプトで一括補完するしかない。
三つのルールは入れ子の全オブジェクト層に再帰的に適用する必要がある。最上位だけ直して子オブジェクトを放置すれば、やはり 400 になる。最小の適合例は次の通り:
{
"type": "object",
"properties": {
"intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
"note": { "type": ["string", "null"] }
},
"required": ["intent", "note"],
"additionalProperties": false
}
三、これらの書き方は即 400:禁止語と無効語
strict モードは JSON Schema のサブセットしかサポートしない。キーワードを二種類に分けて処理する:
| 分類 | キーワード | strict モードでの挙動 |
|---|---|---|
| 即拒否 | $ref / $defs 参照、allOf、not、dependentRequired、dependentSchemas、if/then/else |
API がエラーを返し、リクエスト失敗 |
| 黙って無効 | pattern、minLength、maxLength、format、minimum、maximum、multipleOf(ファインチューニングモデル) |
エラーも強制もなし。正規表現の制約はアプリ層で自前検証 |
扱い方は異なる:前者は改写必須——$ref をインライン展開し、allOf を properties に統合する。後者は残しておける(受け付ける設定もある)が、防衛線として絶対に扱わないこと。"pattern": "^v\\d+\\.\\d+\\.\\d+$" でバージョン形式を保証しようとする書き方は strict の下では無防備であり、レスポンス取得後に明示的な検証をもう一度走らせる必要がある。最上位にもう一つのルール:schema のルートは配列や裸のユニオン型ではいけない。object で一層包むこと。
四、ハードリミット:5000 属性、10 層ネスト、12 万文字
語彙がすべて適合していても、規模が上限を超えればエラーになる。OpenAI 公式のハードな数字:
- schema 全体でオブジェクト属性は最大 5000 個、ネストは最大 10 層(Anthropic 側のネスト上限は約 6 層);
- 属性名・定義名・列挙値・const 値の文字列総長は 120000 文字まで;
- 列挙値は合計最大 1000 個。文字列列挙が 250 個を超える単一プロパティでは、総長 15000 文字以内という条件が付く。
普段はこれらに触れないが、「辞書まるごと列挙値にする」や「三層のオブジェクトグラフを一層に圧縮する」は二つの現実の失敗パターンだ。出会ったら分割する:巨大 schema を複数回の呼び出しに分けるか、構造をフラット化する。なお、出力キーの順序は schema 内のキー順序と一致する。固定順序に依存する下流パーサーはこれを特性として利用できる。
五、スクリプトで緩い schema を一括 strict 化する
手作業で層ごとに直すと取りこぼす。次の再帰スクリプト(DevToolLab の 2026 ガイドが示したパターン)は「全オブジェクト封印・全鍵必須」を一括で補う:
def make_strict(schema: dict) -> dict:
"""additionalProperties:false + 全鍵必須、全層に再帰。"""
if isinstance(schema, dict):
if schema.get("type") == "object" and "properties" in schema:
schema["additionalProperties"] = False
schema["required"] = list(schema["properties"].keys())
for value in schema["properties"].values():
make_strict(value)
elif isinstance(schema, dict):
for value in schema.values():
make_strict(value)
elif isinstance(schema, list):
for item in schema:
make_strict(item)
return schema
併せて使うワークフローの提案:まずサンプル JSON から schema の骨格を逆推定する(本サイトの /convert/schema ツールページは JSON から Schema への片方向の逆推定を行う)。骨格を起点にし、strict の三つの硬いルールで引き締め、最後に make_strict で底を張る。スクリプトは形状しか扱わない点に注意。null 許容ユニオン・列挙・意味フィールドは依然として人手で決める。$ref を含む schema は先にインライン展開してから渡すこと。
六、Anthropic の等価な書き方:tool-as-schema
Anthropic には対応する strict: true スイッチがない。2026 年の定石は、レスポンス schema をツールの input_schema として登録し、tool_choice でモデルにその呼び出しを強制することだ:
await anthropic.messages.create({
model: "claude-sonnet-4-6",
tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
tool_choice: { type: "tool", name: "emit" },
messages,
});
ツール呼び出しチャネル自体が JSON を検証するため、効果は strict モードと等価だ。差異は細部にある:Anthropic のネスト上限は約 6 層、.optional() ではなく .nullable() をサポートする。三家(OpenAI・Anthropic・Gemini)が受け付ける schema サブセットは完全には同じではない。一份の schema を無改変で横断利用するのは信頼できず、モデルを切り替えたら再検証が必要だ。
七、refusal・切断・タイムアウトを先に振り分ける
strict モードで不正なものを受け取ったとき、原因は三種類しかなく、対応はまったく別物だ:
- refusal:モデルが実行を拒否(安全でないリクエストなど)。レスポンスの
refusalフィールドが真なら、JSON を読んでも意味がなく、人手へ回すかリクエストを書き直す。 - 切断(truncate):
finish_reasonがlengthの場合、max_tokens が足りず出力は物理的に不完全。schema の制約では切断を救えない。予算を増やすか出力構造を圧縮する。判定と部分復旧は切断 JSON の判定と修復の記事を参照。 - 破形:供給側がサブセットを完全にサポートしない場合でも壊れた JSON が届き得る。リトライ時に「もう一度」だけ言わず、具体的な検証エラーの原文をプロンプトに添える——「severity は low/medium/high/critical のいずれか。urgent が出力されました。修正して再出力してください」。エラー文脈つきのリトライは平均リトライ回数を 3 回から約 1.5 回に下げられる。
リトライには硬い上限(例えば 2 回)を設け、超過したらより小さなモデルで訂正するか人手のキューへ降格させる。一本の悪い出力でパイプライン全体を止めさせない。
八、リリース前チェックリスト
| 検査項目 | 合格基準 |
|---|---|
| required | 全オブジェクトの全フィールドが required にある |
| additionalProperties | 全オブジェクトで明示 false、最深層まで再帰 |
| 任意の意味論 | ["string", "null"] ユニオンで模擬。裸の optional はなし |
| 禁止語 | $ref / allOf / if-then-else / dependentRequired を含まない |
| 無効語 | pattern・format 系の制約はアプリ層で二重検証 |
| 規模 | 属性 ≤5000、ネスト ≤10 層、文字列総量 ≤12 万文字 |
| 振り分け | refusal / length / 解析失敗の三路を分離処理 |
| リトライ | 検証エラー原文を添え、上限 2 回、超過で降格 |
| 意味論 | schema 外の evals またはフィールド級のアサーション |
このリストを通れば形状の信頼性はほぼ鎖でつながれる。意味論と契約の進化(schema のバージョン化、壊れた schema を CI で先に赤くする方法)はSchema 契約を CI に溶接するを参照。
FAQ
strict モードはフィールド値の正しさを保証するか?
できない。デコード時に文法と形状を鎖でつなぎ、「全ての鍵が存在し、型が合い、列挙が合法」であることだけを保証する。値の意味論は保証しない。モデルは形式は正しいが内容が誤ったデータを出し得る。意味層は評価セットかフィールド級アサーションで守る。
なぜ任意フィールドも required に書くのか?
strict の状態機械は宣言された全属性が到達可能であることを要求し、required の省略は検証で拒否される。任意の意味論は ["string", "null"] ユニオン型で模擬する:フィールドは必ず現れ、値は null でよい。下流は null で欠落を判断する。
pattern と minLength は完全に無意味か?
ファインチューニングモデルと多くの strict 設定では強制されない。エラーにもならないため最も危険だ——防衛線があると思っているのに実はない。これらの制約に依存するレスポンスは、受領後に ajv や jsonschema で明示的に再検証する。
strict はレスポンスを遅くするか?
新しい schema の初回リクエストのみコンパイルコストがかかる(典型的には 10 秒以内、複雑な schema は 1 分に達する)。コンパイル产物がキャッシュされた後は、最初の token に約 5〜8% の遅延が増えるだけだ。定常状態ではほぼ無感。schema が頻繁に変わる場合にのみコストになる。
モデルバージョンを変えたら何を再検証する?
三つ:そのバージョンがサポートする schema サブセットの変化、refusal と finish_reason フィールドの有無、ネストと規模上限の引き締まり。供給側ごとに受け付けるサブセットが異なるため、schema を横断で再利用する前に最小リクエストで一つ検証する。