JSON修復ガイド:壊れたLLM出力の救出と信頼の境界線
要点:markdownコードフェンスで囲まれ、末尾カンマやPythonリテラルを含むLLM出力は、厳密なパーサーには一切受け付けられません。修復ツールが実際に直せる9種類のエラーと直せない4種類の境界を整理し、状態機械と正規表現という2つの実装方式の違いを解説。jsonrepairとjson-repairの二重スタック接続手順と、修復結果をスキーマ検証で裏付ける方法までを扱います。

厳密なパーサーは壊れた入力に対して一切寛容ではありません。エラーメッセージと行番号を1つ渡すだけで、データは1バイトも返してくれません。修復ツールの存在意義は「完全な失敗」を「とりあえず動く状態」に変えることです。ただし、修復が補ったものは常に意図に対する最良の推測であり、正しさの保証ではありません。
一、壊れたJSONはどこから来るのか:3つの発生源
修復は万能ではないので、まず入力の正体を見極めます。実務で非標準JSONが生まれる場所は3つに集約されます。
- LLMの出力。言語モデルはトークン単位でテキストを生成しており、JSONシリアライザーを実行しているわけではありません。「JSONのみを出力して」と頼んでも、モデルは
```jsonのコードフェンスで囲んだり、「はい、こちらがデータです」という一言を前置きしたり、末尾カンマを残したり、トークン上限に達してオブジェクトの途中で停止したりします。 - 他の言語からのコピー。
console.logで出力したJavaScriptオブジェクトにはシングルクォートと引用符なしのキーが付き、Pythonの辞書はTrue/False/Noneと表示されます。この「JSONに似ている」テキストはJSON.parseに渡した瞬間に爆発します。 - JSON5/JSONC設定ファイル。tsconfigのようなファイルはコメントと末尾カンマを合法的に許容します。これをそのまま厳密なパーサーに渡すと、やはり拒否されます。
3つの発生源で対処法は異なりますが、修復ツールはすべてをカバーできます。ただし条件があり、エラーが修復ツールが宣言している「修復可能リスト」に含まれている必要があります。
二、修復できる9種類:修復ツールの本当の得意分野
jsonrepairライブラリのドキュメントと各ツールベンダーが公表している能力リストを総合すると、自動修復できるエラーは9種類に分類できます。
| 分類 | 壊れた入力 | 修復結果 |
|---|---|---|
| 末尾カンマ | [1, 2, 3,] |
[1, 2, 3] |
| シングルクォート/全角引用符 | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| 引用符のないキー | {name: 'Ada'} |
{"name": "Ada"} |
| コメント | {"a": 1 /* 注釈 */} |
{"a": 1} |
| Pythonリテラル | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| markdownフェンス | ```json {...} ``` |
{...} |
| カンマの欠落 | [1 2] |
[1, 2] |
| 括弧/引用符の未閉鎖 | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP/文字列連結 | cb({...})、"x" + "y" |
{...}、"xy" |
この9種類に共通するのは、データはすべて揃っていて、構文だけが壊れているという点です。修復ツールは句読点とラッパーを調整するだけで、値には一切触れません。次の細かい点は個別に覚えておく価値があります。
- 先頭ゼロ付きの数値は文字列に変換される:
007は7ではなく"007"に修復されます。桁情報を失わないためです。フィールドがもともとテキスト形式のコード番号なら正しい動作ですが、本当に数値なら自分で判断する必要があります。 - 裸の単語は文字列になる:
NaNは数値として修復できず、実装によって"NaN"になるものとnullになるものがあります。ライブラリごとに挙動が違うので、パイプラインに組み込む前に一度試してください。 - 入力がすでに正当なJSONならそのまま返す:修復ツールには厳密なパースの高速経路が組み込まれており、正当な入力は修復ロジックを通らないため、「修復するほど壊れる」ことはありません。
三、修復できない4種類:信頼の境界線の反対側
修復ツールの能力限界も同じく明確です。次の4種類は期待しないでください。
- HTMLエラーページや純粋な文章。入力にJSON構造がまったく存在せず、どのツールもデータを無から生成することはできません。
- 構文的には正当だがデータが間違っているケース。キーのスペルミス、値の位置間違い、数値を文字列として保存——これらは意味的な問題であり、構文レベルでは完全に合法なので、どの修復ツールも素通しさせます。
- 切断によって失われたデータ。補完機能は
{"items": [{"id": 1}, {"naを正当なJSONに修復できますが、nameフィールドの値は二度と戻りません。修復結果は「正当だが不完全」なオブジェクトです。本番環境では、補完するか再試行するかを決める前に、必ずstopReason === "max_tokens"を確認してください。 - 重複キーと曖昧な構造。同名のキーが2つある場合、どちらが有効になるかはパーサーの実装に依存します。責任ある修復ツールはstrictモードを提供し、黙って一方を選ぶのではなくエラーを投げます。
信頼の境界線を一文でまとめると、修復は「最良の推測」であって「正しさの保証」ではないということです。検証せずに修復結果を下流へ流すことは、目立つ構文リスクを、より見えにくいデータリスクに交換するのと同じです。
四、実装の2流派:URL一つで違いが試せる
市場の修復ツールには2つの実装流派があり、その能力差は特定の入力ですぐに現れます。
正規表現置換派は壊れたパターンをグローバルに検索・置換します。次の入力を考えてください。
{"url": "http://example.com", 'note': 'fine'}
「シングルクォートをダブルクォートに変える」正規表現はURLの中身まで巻き込み、「すべての // を削除する」コメント除去の正規表現は http:// を真っ二つにします。文字列の内側と構造の外側では見た目が同じであり、正規表現には区別できません。
一文字ずつの状態機械派はパース状態を追跡します。現在ダブルクォート文字列の中にいるのか、シングルクォート文字列の中なのか、行コメントの中なのか、ブロックコメントの中なのか、値を待っている状態なのか。' を見つけたとき、まず「自分は文字列の中にいるか」を判断してから、引用符を変換するかスキップするかを決めます。http://example.com はダブルクォート文字列の中にあるので、状態機械は中の // がコメントではなくデータだと認識し、そのまま保持します。jsonrepairやjson-healerといったライブラリはこの流派で、コミュニティの解説で繰り返し強調されている「修復ツールは検索置換ではない」という言葉はまさにこのことを指します。
修復パイプラインの完全な順序(devkitsが公開している実装の流れ)も見る価値があります。フェンス剥離 → 全角引用符の正規化 → 最初の対応の取れたブロック抽出 → コメント除去 → キーへの引用符付与 → 末尾カンマ除去 → リテラル変換 → 最後に JSON.stringify で再シリアライズ。最後の再シリアライズが鍵です。前段で何をしていようと、出力はパース結果から再生成されるため、下流のどの厳密なパーサーも受け入れられます。
五、コードでの接続方法:順序化されたパースチェーン
コードに修復を組み込む場合、ライブラリ選定よりも順序が重要です。json2toonとaijsonmedicが公開しているパターンに沿って整理すると、順序はこうなります。切断チェック → JSON区間の抽出 → 厳密なパース → 修復によるフォールバック → スキーマ検証。
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// 切断された出力を修復してもデータは欠けたまま。再試行する
throw new Error("Truncated output: retry with a higher max_tokens");
}
// JSON区間を抽出:LLMは前後に挨拶を付けることがある
const start = text.search(/[[{]/);
const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
try {
return JSON.parse(candidate); // 正当な入力は高速経路へ
} catch {
return JSON.parse(jsonrepair(candidate)); // 修復によるフォールバック
}
}
Python側では json-repair パッケージ(スター数4,700以上)の loads() が直接オブジェクトを返します。
from json_repair import repair_json
import json
broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}
さらに2つの実務的な細部があります。
- スタックの整合。フロントエンドとバックエンドの両方で修復する場合は、意味的に同源の実装を選びます(Pythonのjson-repairとそのTS移植版
@yarmu/json-repair、または同一の整合性コーパス485件を両側が通過しているjsonmend)。そうしないと、同じ出力がフロントエンドではAに、バックエンドではBに修復され、問題の特定がさらに難しくなります。 - 修復ログの有効化。
@yarmu/json-repairはlogging: trueで毎回の修復操作の配列を返します。本番の修復率が急に上がったとき、通常はプロンプトかモデルのバージョンが変わった合図です。エラーレポートよりも早い信号になります。
修復の後に省略できないステップがもう一つあります。スキーマ検証です。構文が直ってもデータが使えるとは限りません。欠落フィールド、型の不一致、余分なキーはすべてスキーマで捕捉します。契約テストの考え方がそのままここに適用できます。「JSON Schema契約テストのやり方」を参照してください。
六、予防チェックリスト:修復しなくて済むのが最善
修復はあくまでフォールバックです。源流で壊れたJSONを減らすことが本質的な勝利です。優先度順に並べます。
- Structured Outputs(json_schemaモード):デコード段階でスキーマによって制約されるため、末尾カンマはそもそも生成されません。OpenAIのstrictモードの失敗率は約0.1%ですが、
additionalProperties: falseなどの厳しい要件が代償です。 - JSONモード(json_object):構文の正当性だけを保証し、形状は保証しません。トークン上限による切断も依然として起こります。
- 明示的な指示:JSONモードのないエンドポイントでは、「フェンス禁止・コメント禁止・末尾カンマ禁止・オブジェクトのみ出力」と明記するだけでエラー率を70〜80%削減できます。
- temperatureを下げ、トークン上限を上げる:前者は文章への脱線確率を減らし、後者は切断を減らします。
- エラー付きの再試行:検証が失敗したら、壊れた出力と「JSON path + エラーメッセージ」を会話に添えてもう一度要求します。モデルは正確なエラーがあれば概ね自己修正できます。
実務では「structured outputs + 修復フォールバック + スキーマ検証」の3層を重ねて使えば、修復で処理できないシナリオはほぼなくなります。
七、オンラインツールの役割分担:方言変換と修復は別物
当サイトのツールボックスには、このパイプラインに対応する2つの落とし所があり、それぞれ担当範囲が異なります。
- **方言系の問題(コメント、シングルクォート、末尾カンマ)**はJSON5変換に直接渡します。JSON5と標準JSONの相互変換はまさにこの3種類をカバーし、変換の意味は明確で推測を含みません。入力全体がJSONC/JSON5ファイルなら、「修復」よりも変換のほうが予測しやすくなります。方言自体の取捨選択は「JSON5とJSONCガイド」を参照してください。
- 修復の後はJSON解析ツールで検証・整形し、エラーを行と列に特定し、修復結果が本当に厳密なパーサーに受け入れられるかを確認します。
- **ライブラリ系の問題(Pythonリテラル、切断補完、JSONPラップ、markdownフェンス)**は現時点ではコード側のjsonrepair / json-repairに頼る必要があります。ブラウザ側に同等のワンクリック修復はありません。この2種類の修復は「意図の推測」を伴うため、汎用変換ツールに詰め込むよりローカルライブラリのほうが安全です。
手元にあるのが壊れたデータではなくエラーメッセージなら、まず「JSONパースエラーの修り方」でエラーを座標に翻訳してから、手作業で直すか修復するかを判断してください。
よくある質問
JSON修復はデータを壊してしまいませんか?
修復可能な9種類については句読点とラッパーしか変更せず、値には触れません。文字列内部の //、カンマ、波括弧は状態機械が識別してそのまま保持します。ただし切断補完によるオブジェクトはデータが欠け、先頭ゼロ付き数値は文字列になり、NaN の扱いはライブラリごとに異なります。修復後のキーフィールド確認は必須の作業です。
修復と検証はどんな関係ですか?
検証は「どこが不正か」を教えるだけですが、修復は「正当なJSONそのもの」を出します。信頼できるのは両方やる方法です。まず修復し、次に検証する。スキーマ検証で型と必須フィールドを捕捉し、構文検証でパーサーが受け入れることを確認します。検証せずに修復だけするのは、目立つ構文エラーを、より見えにくいデータエラーに交換するのと同じです。
LLMの出力が常に ```json フェンスに囲まれる場合は?
短期的には抽出で対処します。最初の { または [ から最後の } または ] までの内容を取り出してパースします。フェンス剥離に対応した修復ツールなら出力全体をそのまま処理できます。長期的にはstructured outputsか「markdownフェンス禁止」の明示的な指示に頼り、生成段階からフェンスを作らせないことです。
jsonrepairとjson-repair、どちらを選ぶべきですか?
JavaScriptスタックにはnpmのjsonrepair(ストリーミングtransform対応)、PythonスタックにはPyPIのjson-repairを使います。両端で修復するなら意味的に同源の組み合わせ、たとえばjson-repairとそのTS移植版を選び、同一入力に対して両側の修復結果が一致することを保証します。
修復ツールは日本語や全角引用符を処理できますか?
処理できます。日本語入力で打たれた全角引用符(“”)や全角スペース、ファイル先頭のBOMはすべて一般的な修復リストに含まれ、全角引用符は半角に正規化されます。修復後に検証ツールを一度通せば確認できます。