JSON コメントの書き方: 使えない時の JSONC / JSON5 など 4 つの回避策

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

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

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

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

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

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

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

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

Q: YAML ではどうなのですか?

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

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

書けません。標準の JSON（RFC 8259）はドキュメント内のどの位置にもコメントを許可していません。.json ファイルの中に // や /* ... */ を書くと、厳密なパーサーは「Unexpected token」エラーで失敗します。これは仕様の構造上の制約で、Section 2 の文法がコメントを定義していないためです。一方 Section 9 は「パーサーは非 JSON 形式や拡張を受け入れてもよい（MAY accept non-JSON forms or extensions）」と認めており、これが JSONC や JSON5 が仕様違反にならない根拠になっています。

どうしても JSON にコメントを書きたい、設定値をコメントアウトして残したい、あるいは説明用のコメント行を入れたいという場合は、次の 4 つの実用的な選択肢があります。

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

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

先に結論だけ押さえたい場合は、用途ごとに次のように選びます。

VS Code や Microsoft 系の設定ファイルを書いている場合は JSONC を使います
新規プロジェクトの設定フォーマットを選ぶ場合は JSON5 を使います
パーサーが厳格で差し替えできない場合は _comment フィールドかコメント除去で対応します

コメントを除去した JSON を整形・検証するには FormatArc の JSON Formatter を使ってください。ブラウザで完結し、データは手元から出ません。読みやすい 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 のまま後述の回避策パターンを使う

実装ごとの対応状況: それぞれが実際に許可する機能

次の表は、よくある 5 つの「非 JSON」機能を、厳密な標準と 2 つのスーパーセットで比較したものです。RFC 8259 の列は RFC 8259 Section 2 の文法（ECMA-404 に成文化された文法と同じもの）を反映しています。JSON5 の列は公開された JSON5 仕様を、JSONC の列は VS Code 向けに文書化された Microsoft の非公式拡張を反映しています。

機能	RFC 8259 で許可される?	JSONC	JSON5
行コメント `//`	不可	対応	対応
ブロックコメント `/* */`	不可	対応	対応
末尾カンマ	不可	任意	対応
キーのクォート省略	不可	非対応	対応
シングルクォート文字列	不可	非対応	対応

RFC 8259 の列がすべて「不可」なのは、Section 2 の文法にこれらの機能を受け付ける production rule が存在しないためです。文字列はダブルクォートで囲む必要があり、キーは文字列で、オブジェクトや配列の最後の値の後ろに要素を置くこともできません。JSON5 は仕様が ECMAScript 5 の構文を明示的に追加しているため、5 つすべてに対応します。JSONC は 2 種類のコメントを常に追加しつつ、厳密な JSON のダブルクォートのキーと文字列を維持します。末尾カンマの対応はパーサー依存（JSONC の仕様はパーサーが受け付けてもよい（MAY）としており、リファレンス実装の jsonc-parser は allowTrailingComma をデフォルトで無効にしています）であり、セルが「対応」ではなく「任意」になっているのはそのためです。

標準 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
  }
}

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

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

package.json にコメントを書く

package.json は npm が読み込む標準 JSON ファイルなので、// や /* */ のコメントアウトはできません。書くと npm install が JSON.parse の段階で失敗します。ただし npm は知らないトップレベルのキーを無視するため、回避策パターンをそのまま応用できます。

よく使われるのは、"//" という慣習的なキーにメモを入れる方法です。

{
  "//": "private レジストリを使う設定。社内 CI でのみ有効",
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc -p ."
  }
}

同じキーは 1 オブジェクト内で 1 回しか使えないため、複数の説明を残したいときは配列を使います。

{
  "__comments": [
    "deploy 用のスクリプトはこのファイルでは管理しない",
    "engines は CI の Node バージョンと揃えること"
  ],
  "name": "my-app",
  "engines": { "node": ">=20" }
}

npm 自体はこれらのキーを無視しますが、npm publish で公開するパッケージにはメモも同梱されます。社内ツールやプライベートリポジトリで使う package.json に向いた方法です。設定の意図をしっかり残したい場合は、後述のコメント除去パターンで JSONC として書いてから公開用に変換するほうが安全です。

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

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);

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

Python で JSONC / JSON5 を扱う

Python の標準ライブラリ json は厳密な JSON しか読めないため、JSONC や JSON5 をそのまま json.loads に渡すとコメント行で失敗します。対処は 2 通りあります。

軽量に済ませたい場合は、標準ライブラリの re でコメントを除去してから json.loads に渡します。

import json, re

def load_jsonc(text):
    text = re.sub(r"//[^\n]*", "", text)        # 行コメント
    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)  # ブロックコメント
    return json.loads(text)

with open("tsconfig.json", encoding="utf-8") as f:
    config = load_jsonc(f.read())

この正規表現は文字列リテラルの中に // を含むデータでは誤って削ってしまうため、自分で管理しているファイル以外には使わないでください。

末尾カンマやクォート省略まで含めて正しく読みたい場合は、専用ライブラリを使います。JSONC なら jstyleson、JSON5 なら json5 または pyjson5 が定番です。

# pip install jstyleson json5
import jstyleson
import json5

config = jstyleson.load(open("settings.json", encoding="utf-8"))   # JSONC
data = json5.load(open("config.json5", encoding="utf-8"))          # JSON5

設定を読むだけなら正規表現でも足りますが、入力が信頼できない、あるいは末尾カンマやシングルクォートが混ざる可能性があるなら、専用ライブラリのほうが安全です。

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

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

FormatArc JSON Formatter で整形済み JSON を表示している画面

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

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

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

よくある質問

RFC 8259 は JSON コメントについて何と書いていますか?

RFC 8259 は「コメント」という単語自体を一度も使っていません。Section 2 の JSON 文法（ABNF）で「トークンの間に置ける空白は space / tab / line feed / carriage return の 4 種のみ」と定義されており（ws = *( %x20 / %x09 / %x0A / %x0D )）、// や /* */ を受け付ける production rule が存在しないため、厳密なパーサーは「Unexpected token」エラーで拒否します。一方 Section 9 では「JSON パーサーは非 JSON 形式や拡張を受け入れてもよい（MAY）」と明記されており、これが JSONC や JSON5 が仕様違反にならない根拠です。

`.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 の違いを参照するか、YAML の書き方ガイドに直接進んでください。

JSON そのものをもっと理解したい場合:

JSON とは — JSON の基本
JSON の書き方ガイド — 厳密な JSON の構文ルール

JSONC や JSON5 を選んで、その出力を扱う場合:

JSON 整形のコツと注意点 — コメント除去後の出力を読みやすくする
JSON Parse Error の解決方法 — コメントの消し忘れが原因のエラーも含む
JSON 末尾カンマエラーの直し方 — JSON5 が許す、もう 1 つの構文エラー

コメントが必要でフォーマットを変えられる場合:

YAML と JSON の違い — 設定ファイル向けの代替フォーマット
YAML の書き方ガイド — コメントが欲しいときに使える選択肢

まとめ

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

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

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

選択肢 1: JSONC — JSON with Comments

JSONC のパース方法

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

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

実装ごとの対応状況: それぞれが実際に許可する機能

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

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

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

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

package.json にコメントを書く

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

Python で JSONC / JSON5 を扱う

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

よくある質問

RFC 8259 は JSON コメントについて何と書いていますか?

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

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

JSON5 は標準仕様ですか?

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

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

YAML ではどうなのですか?

関連記事

まとめ

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

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

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

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