コメントを書きたいときは、JSON にコメントを足した形式か、最初からコメントを書ける別の形式を選びます。このページでは、JSONC・JSON5・YAML・TOML を比べて、実際に読ませます。最後に、このノートの要点をまとめます。

JSONC：JSON にコメントを足した書き方

JSONC（JSON with Comments）は、JSON にコメントを許した拡張です。jsonc.org は、VS Code の設定ファイルの形式を明文化するための仕様の草案を出しています（草案であって、確定した標準ではありません）。

  • 行コメントは // から行末まで、ブロックコメントは /* */
  • 末尾カンマは、パーサーが「対応してよい」（MAY）とされる。参照実装では、既定でオフ
  • 推奨する拡張子は .jsonc。.json を使うときは、モードを示す印を付ける

前のページで見た wrangler.jsonc は、この形式のファイルです。

JSON5・YAML・TOML

JSON5 は、「人が手で書き、保守しやすくするための、JSON の拡張案」です。JSON の上位集合で、コメント、末尾カンマ、引用符なしのキー、シングルクォートの文字列などを許します（spec.json5.org）。

YAML 1.2 と TOML 1.0.0 は、最初からコメントを書ける別の形式です。どちらも # から行末までがコメントです。

実際に読ませる

3 つの形式に、それぞれコメントを入れて読ませます。

import JSON5 from "json5";
import YAML from "yaml";

console.log("JSON5:", JSON.stringify(JSON5.parse(`{
  // c
  /* b */ a: 1, 's': 'x',
}`)));
console.log("YAML:", JSON.stringify(YAML.parse("# c\na: 1 # d\ns: x\n")));
console.log("YAML(JSON as YAML):", JSON.stringify(YAML.parse('{"a": 1, "s": "x"}')));

import tomllib
print(tomllib.loads("# c\na = 1 # d"))

コメントは、どの形式でも、読んだ結果には残りません。3 つ目の出力は、JSON のテキストを YAML として読んでも同じデータになる、という例です。YAML の仕様は、この点について次のように述べています。

By sheer coincidence, JSON was almost a complete subset of YAML (both syntactically and semantically).

出典: https://yaml.org/spec/1.2.2/（取得日: 2026-09-22）

JSONC の仕様の所在は、jsonc.org 以外は確認していません。

YAML の仕様が答えている点

前のページの話とつながる箇所が、YAML の仕様にあります。

Comments are a presentation detail and must not be used to convey content information.

出典: https://yaml.org/spec/1.2.2/（取得日: 2026-09-22）

「コメントは表示の詳細であり、内容の情報を運ぶために使ってはならない」という意味です。Crockford が心配したと伝えられる「コメントに指示を入れる」使い方を、YAML は仕様の側で禁じています。同じ懸念に、別の形式が別の答えを出している、と読めます。ただしこれは私の解釈で、YAML の仕様が JSON の件に触れているわけではありません。

このノートの要点

  1. JSON の文法（json.org・RFC 8259）に、コメントの仕組みは無い。標準の JSON.parse は、コメントを構文エラーにする
  2. 拡張子が同じ .json でも、tsconfig.json は通り、package.json は通らない。決めているのは、拡張子ではなく、読む側のパーサーである
  3. JSON は、Ajax 期のデータ交換の形式として生まれた。人が手で書き続ける設定ファイルの書式ではない（この関係は推測）
  4. コメントを外した理由は、「パーサーへの指示が入ると相互運用性が壊れる」と伝えられている。原文は取得できておらず、断定はしない
  5. コメントを書きたいなら、JSONC・JSON5・YAML・TOML のように、コメントを許す形式を選ぶ。ファイルの拡張子（.jsonc など）と、読む道具が対応しているかを確かめる

書きたいのが「メモ」なのか「設定」なのか、それとも「別の道具に渡すデータ」なのかで、選ぶ形式は変わります。