JSON vs JSONC（コメント付きJSON）

JSONC（JSON with Comments）は、標準JSON形式の拡張で、ドキュメント内にシングルライン（//）およびマルチライン（/* */）コメントを記述できるようにしたものです。公式の標準ではありませんが、開発者ツールで広く採用されており、特にVisual Studio Codeの settings.json や tsconfig.json などの設定ファイルで顕著です。

JSONCが存在する理由:

Douglas Crockfordが策定したオリジナルのJSON仕様は、フォーマットをシンプルに保ち、パースディレクティブやメタデータアノテーションなどの悪用を防ぐために、意図的にコメントを除外しました。しかし、設定ファイルは主に人間が読み書き・保守するものであり、説明的な注釈の追加、デフォルト値のドキュメント化、設定の一時的な無効化ができないことは、実際の開発体験に摩擦をもたらします。JSONCは、人間が利用するファイルにコメントを許可することで、このギャップに対応しています。

JSONとJSONCの主な違い:

標準JSONは、定義された文法の一部でないコンテンツを一切許可しません。準拠するJSONパーサーは、// や /* */ を検出すると構文エラーをスローします。一方、JSONCパーサーはパース前にコメントを除去し、実質的に空白として扱います。JSONCは通常、末尾カンマも許可するため、行の並べ替えが容易になります。

JSONCがサポートされている場所:

• tsconfig.json（TypeScriptコンパイラ設定）— 常にJSONCとしてパースされます
• VS Codeの settings.json、launch.json、extensions.json
• ESLint設定（フラットコンフィグコメント使用時の .eslintrc.json）
• Microsoftツールが使用する jsonc-parser npmパッケージ JavaScriptの JSON.parse()、Pythonの json.loads()、ほとんどのHTTPクライアントなどの標準JSON APIはJSONCをサポートしていません。

開発者がよくやるミス:

最も多いミスは、標準JSONパーサーで解析されるファイルにJSONC構文を使用することです。例えば、package.json にコメントを追加すると、npmは厳密なJSONパーサーを使用しているため npm install が失敗します。もうひとつのミスは、すべてのJSONツールやライブラリがJSONCをサポートしていると想定することです。利用側がコメントをサポートしているか確信がなければ、コメントを含めないでください。また、JSONCとJSON5を混同する開発者もいます。JSON5はクォートなしのキーやシングルクォートの文字列など、追加の構文を許可する別のスーパーセットです。

ベストプラクティス:

利用側のツールが明示的にサポートしている場合にのみJSONCを使用してください。標準JSONファイルの場合は、別のREADMEにドキュメントを追加するか、"_comment" キー規約を使用しましょう。JSON設定ファイルを読み取るライブラリを作成する際は、開発者体験を向上させるためにJSONCパースのサポートを検討し、それを明確にドキュメント化してください。