JSON にコメントを書く方法 — JSONC・JSON5・実用的な回避策

JSON にコメントは書けますか? — 先に結論

書けません。標準の JSON（RFC 8259）はドキュメント内のどの位置にもコメントを許可していません。.json ファイルの中に // や /* ... */ を書くと、厳密なパーサーは「Unexpected token」エラーで失敗します。

どうしてもコメントを残したい場合は、次の 4 つの実用的な選択肢があります。

• JSONC — VS Code が採用している「コメント付き JSON」
• JSON5 — コメント・末尾カンマ・ゆるい文法を含む、仕様化された JSON のスーパーセット
• 標準 JSON の中に "_comment": "..." のようなダミーフィールドを置く
• パース前にコメントを除去する

この記事では、それぞれの選択肢の使いどころ、選び方、そしてコメント付きの JSON を標準 JSON に変換するための具体的な手順を解説します。

JSON がコメントを許可しない理由

JSON の設計者である Douglas Crockford は、意図的にコメントを仕様から外したと語っています。コメントにパース用のディレクティブが埋め込まれ、相互運用性が壊れる事例が実際にあったためです。結果として JSON は次のようにシンプルな形になりました。

• 小さい — 文法が 1 ページに収まる
• 曖昧さがない — 値の解釈は常に 1 通り
• ポータブル — どの言語の組み込みパーサーも同じ挙動

代わりに、「なぜこの設定値なのか」を JSON ファイル自体に書き残すことはできません。これがトレードオフであり、多くのツールが JSONC や JSON5 のようなスーパーセットを使う理由でもあります。

JSON そのものの文法が知りたい場合は JSON の書き方ガイド を参照してください。

選択肢 1: JSONC — JSON with Comments

JSONC は Microsoft が VS Code で採用している非公式の拡張で、JSON に次の 2 つを追加したものです。

• // 行末までのコメント
• /* 複数行にまたがるコメント */

それ以外は通常の JSON と同じです。典型的な JSONC ファイルは次のような見た目です。

{
  // VS Code 起動時に使用するテーマ
  "workbench.colorTheme": "Default Dark Modern",

  /* エディター全体の設定
     すべての言語に適用される */
  "editor.tabSize": 2,
  "editor.formatOnSave": true
}

VS Code の settings.json、tsconfig.json、launch.json、そして Microsoft 系のツールはほとんどが JSONC を前提にしています。Deno の設定ファイル（deno.json）などでも採用されています。

JSONC のパース方法

JSONC は組み込みの JSON.parse では読めないので、専用ライブラリが必要です。

Node.js:

// npm install jsonc-parser
import { parse } from "jsonc-parser";
const data = parse(sourceText);

Python:

# pip install jstyleson
import jstyleson
data = jstyleson.loads(source_text)

VS Code 本体は自前の JSONC パーサーを持っているため、settings.json にコメントを書いても壊れません。

選択肢 2: JSON5 — 仕様化された拡張版

JSON5（json5.org）は正式な仕様を持つ JSON のスーパーセットで、ECMAScript 5 から借りたいくつかの便利な機能を追加しています。

• 行コメントと複数行コメント
• オブジェクトと配列の末尾カンマ
• 識別子として有効なキーのクォート省略
• シングルクォートの文字列
• 行継続によるマルチライン文字列
• 16 進数、先頭・末尾の小数点、Infinity・NaN

JSON5 のファイルはかなりゆるい見た目になります。

{
  // ステージング環境のフィーチャーフラグ
  features: {
    newDashboard: true,
    legacyNotifications: false,
    rateLimitRps: 0xff,
  },
  welcomeMessage: 'Hello, world',
  /* 末尾カンマも OK */
}

JSON5 は仕様が文書化されているため、ほとんどの言語にライブラリがあります。Node.js の json5、Python の pyjson5、Ruby の json5 などが一般的です。

JSONC と JSON5、どちらを使うべきか

似ているようで、それぞれ特性が異なります。

	JSONC	JSON5
公式仕様	なし	あり（spec.json5.org）
コメント	対応	対応
末尾カンマ	一部対応	対応
キーのクォート省略	非対応	対応
シングルクォート文字列	非対応	対応
エコシステム	Microsoft / VS Code	npm 等、独立

選び方の目安は次のとおりです。

• Microsoft / VS Code の設定ファイルを編集している場合は、すでに JSONC なのでそのまま
• 新規プロジェクトで設定フォーマットを選ぶなら、仕様書をツールに指し示せる JSON5 が扱いやすい
• 標準 JSON パーサーとの相互運用が最優先なら、純粋な JSON のまま後述の回避策パターンを使う

標準 JSON を守ったままコメントを残す回避策

サードパーティのサービスが標準 JSON しか受け付けないといった状況では、パーサーを変えずに文字列フィールドとしてメモを残す方法が使えます。

パターン 1: _comment フィールド

{
  "_comment": "上流のタイムアウトに引っかかる前にリトライを増やす",
  "retries": 3,
  "timeout_ms": 5000
}

アンダースコアで始まるキーは慣習的に消費側で無視されることが多く、多くのコードでは通常のデータとして扱えます。もっとも単純な回避策です。

パターン 2: フィールドごとに隣接するコメント用キー

{
  "retries": 3,
  "retries_comment": "これ以上は上流のタイムアウトを超えてしまう",
  "timeout_ms": 5000,
  "timeout_ms_comment": "ロードバランサーのタイムアウトに合わせている"
}

冗長になりますが、どのコメントがどのフィールドに対応するかが明確になります。

パターン 3: メタデータ用の外側ブロック

{
  "$meta": {
    "generated_by": "deploy.sh",
    "purpose": "ステージング環境用のサービス設定"
  },
  "service": {
    "port": 8080,
    "retries": 3
  }
}

トップレベルにメタデータ用のオブジェクトを置くと、本体のペイロードを汚さずにコンテキストを残せます。

これらはすべて実データとしてファイルに書き込むため、厳密なパーサーも受け付けます。デメリットは、追加フィールドがスキーマの一部になるので、消費側にも存在を説明する必要がある点です。

コメントを除去してから標準パーサーに渡す

JSONC や JSON5 のファイルを標準 JSON パーサーに渡したい場合、選択肢は 2 つです。JSONC / JSON5 ライブラリでパースしてから JSON として書き出し直すか、正規表現でコメントを除去するかです。

Node.js で json5 パッケージを使う例です。

// npm install json5
import JSON5 from "json5";
import fs from "node:fs";

const source = fs.readFileSync("config.json5", "utf8");
const data = JSON5.parse(source);
fs.writeFileSync("config.json", JSON.stringify(data, null, 2));

最小限の正規表現による除去もできます。ただし文字列リテラルに // を含む場合は壊れるので、自分で管理しているファル以外にはおすすめしません。

const stripped = source
  .replace(/\/\/[^\n\r]*/g, "")
  .replace(/\/\*[\s\S]*?\*\//g, "");
const data = JSON.parse(stripped);

安全策としては常に専用パーサーを通すほうが無難です。

FormatArc で整形して結果を確認する

標準 JSON になったら、FormatArc の JSON Formatter に貼り付けて整形表示を確認できます。もしパーサーが依然としてエラー（典型的には Unexpected token /）を出すなら、まだコメントが残っている可能性が高いです。原因の一覧は JSON Parse Error の解決方法 にまとまっています。

FormatArc 自体はブラウザ組み込みの JSON.parse を使っているため、JSONC や JSON5 をそのままは受け付けません。手順は次のとおりです。

1. コメントを除去する（もしくは JSONC / JSON5 ライブラリでパースして JSON として書き戻す）
2. 結果を FormatArc の JSON Formatter に貼り付ける
3. 整形された JSON を読み・検証・コピーする

すべてブラウザで完結し、データは手元から出ません。

よくある質問

.json ファイルに // や /* のコメントを書けますか?

厳密なパーサー（JSON.parse・json.loads・encoding/json）で読む場合は書けません。最初のコメントで「Unexpected token」エラーになります。拡張子を .jsonc に変えて JSONC 対応のローダーを使うか、JSON5 に移行してください。

なぜ VS Code は settings.json にコメントを書いても壊れないのですか?

VS Code は settings.json のようなファイルを厳密な JSON ではなく JSONC として扱っているためです。組み込みのパーサーが // と /* */ を受け付けます。同じファイルを JSON.parse で読む他のエディタは、JSONC を理解していなければ失敗します。

JSON5 は標準仕様ですか?

JSON5 は spec.json5.org に公開された仕様を持ちますが、IETF や ECMA の標準ではありません。開発ツール界隈では広くサポートされていますが、API や通信プロトコルで使われる RFC 8259 JSON の代替にはなりません。

_comment フィールドと JSON5、どちらを使うべきですか?

ファイルを多数のツールが読み、その中に厳密な JSON しか扱えないものがあるなら、標準 JSON のまま _comment パターンを使ってください。ファイルを自分の管理下にあるコードだけが読むなら、JSON5 のほうが本物のコメントを書けてノイズも少なくなります。

FormatArc は JSONC や JSON5 に対応していますか?

FormatArc のツールはブラウザ組み込みの JSON.parse を使っているため、厳密な JSON のみ受け付けます。先にコメントを除去するか、JSONC / JSON5 ライブラリでパースしてから結果を FormatArc の JSON Formatter に貼り付けてください。

YAML ではどうなのですか?

YAML は # で標準的にコメントをサポートしています。主な目的がコメントで、フォーマットを変えられるなら、YAML のほうが設定ファイルには向いていることも多いです。詳細は YAML と JSON の違い を参照してください。

関連記事

• JSON とは — JSON の基本
• JSON の書き方ガイド — 厳密な JSON の構文ルール
• JSON Parse Error の解決方法 — コメントの消し忘れが原因のエラーも含む
• YAML と JSON の違い — 設定ファイル向けの代替フォーマット
• YAML の書き方ガイド — コメントが欲しいときに使える選択肢

まとめ

• 標準 JSON はコメントをサポートしていません。仕様上の意図的な制約です
• JSONC は // と /* */ を許可し、VS Code で広く使われています
• JSON5 は仕様化されたスーパーセットで、コメント・末尾カンマ・ゆるい構文を持ちます
• パーサーを変えられない場合は _comment フィールドや外側メタデータブロックで対応できます
• コメントを除去した JSON は FormatArc の JSON Formatter で整形・検証できます