JSONコメントアウトはなぜ書けない?代替法とJSONC活用術

JSONファイルのコメントアウトを試みて、エラーが出て困った経験はありませんか。設定ファイルに注意書きを残したいのに、//や#を書いた途端にJSON.parse()がエラーを吐いてしまう——実はこれ、JSONの仕様上コメントが認められていないために起こる、ごく自然な現象です。とはいえ、コメントを諦める必要はありません。ダミーキーを使った実用的な回避策から、コメントが書けるJSONC・JSON5への乗り換え、さらにはYAML・TOMLへの移行や本番運用でのミス防止策まで、知っておくべき選択肢はたくさんあります。

「エラーの原因を知りたい」という方はもちろん、「チームで安全にコメント運用したい」という方まで、実務にすぐ活かせる内容をまとめています。

JSONにコメントアウトは書けない?結論と基本知識

結論から言えば、JSONの仕様上コメントは一切書けません。//や/* */、#を使うとパーサーがエラーを返し、ファイルの読み込み自体が失敗します。ここではまずエラーの実例と、なぜ仕様としてコメントが排除されているのかという技術的背景を整理します。

//・/* */・#はすべて不可!JSON.parse()で「Unexpected token」が出る原因

JavaScriptのコメント記法をそのままJSONに書くと、JSON.parse()は構文エラーを投げます。JSONの構文にはコメントというトークン自体が定義されていないため、パーサーは//や#を「値でもキーでもない未知の文字」として認識し、即座に処理を停止します。

{
  // ユーザー情報
  "name": "Taro",
  "age": 20 # 年齢
}

上記をJSON.parse()に渡すと、以下のようなエラーになります。

const jsonString = `{
  // ユーザー情報
  "name": "Taro",
  "age": 20
}`;

try {
  JSON.parse(jsonString);
} catch (error) {
  console.error(error.message);
  // Unexpected token '/', ..." // ユーザー情報" is not valid JSON
}

/* */形式のブロックコメントも同様にエラーになります。原因はいずれも共通しており、JSONの文法にコメントという概念が存在しないことに尽きます。

なぜJavaScriptと異なりコメント禁止なのか?RFC 8259とECMA-404の技術的背景

JSONはJavaScriptのオブジェクトリテラルから派生したフォーマットですが、言語ではなく「データ交換フォーマット」として標準化された経緯があります。その仕様を定めているのがRFC 8259(IETFが策定したJSONのインターネット標準仕様)とECMA-404(Ecma Internationalが策定したJSONの構文仕様)です。両仕様書はJSONの文法要素を厳密に定義していますが、コメントに関する構文はどこにも存在しません。

RFC 8259和訳版

※IETF（Internet Engineering Task Force）： インターネット技術の標準化を推進する国際的なコミュニティ。インターネットで使われる通信手順（HTTP、TCP/IP、QUICなど）の標準規格を策定・公開しており、その規格書は「RFC」と呼ばれます。

※Ecma International： 情報通信技術や家電関連の国際規格を策定する標準化団体。Web開発で必須となるJavaScriptの標準仕様「ECMAScript（ECMA-262）」やデータ形式の「JSON（ECMA-404）」などの標準化を手がけています。

これは設計思想に基づく意図的な省略です。JSONの原案者であるDouglas Crockford氏は、コメントを許可すると実装ごとに解釈が分かれ、相互運用性(異なるシステム間でデータをやり取りできる性質)が損なわれるとして、あえてコメント機能を仕様に含めませんでした。

{
  "spec": "RFC 8259 / ECMA-404",
  "supportsComment": false
}

つまり「バグ」や「不便な仕様」ではなく、パーサーの実装をシンプルに保ち、どの言語・どの環境でも同じ結果を保証するための設計判断だと理解しておく必要があります。

API通信やデータ送受信でコメント記述が厳禁とされる理由とセキュリティ上のリスク

API通信で使われるJSONにコメントが書けないことは、実務上はむしろ利点として働きます。理由は主に3つあります。

1. パース処理の一貫性:サーバー・クライアント双方の実装言語が異なっても、同じ構文規則で確実にパースできる
2. データサイズの最適化:コメントを許さないことで余分な情報を含まず、通信量を削減できる
3. 意図しない情報漏洩の防止:デバッグ用のメモや内部情報をコメントに書いたまま本番APIレスポンスに含めてしまうリスクを構造的に排除できる

// 悪い例:もしJSONでコメントが書けたら…という仮定のリスク
// { "apiKey": "xxxx", /* 本番用キー、絶対に外部に出さないこと */ "endpoint": "/v1/users" }

// 実際のJSONではこのような記述自体が不可能なため、
// レスポンスに内部メモが混入する事故が構造的に起きない
const response = {
  "apiKey": "xxxx",
  "endpoint": "/v1/users"
};

このように、コメントが書けないという制約自体が、機密情報の意図しない露出を防ぐセキュリティ設計の一部として機能している点は押さえておきたいポイントです。

JSONでコメントの代わりになる書き方・代替手段

コメントが書けないなら、設定の意図や注意事項をどう残すか。ここでは.jsonの構文を守ったまま説明を書き添える実務的なテクニックと、その際に気をつけるべき落とし穴を紹介します。

「_comment」などダミーキーを使う方法と命名のベストプラクティス

最も広く使われている代替手段が、説明用の文字列を通常のキーとして追加する方法です。_commentや// noteのような、他のキーと衝突しにくい命名を使うのが一般的です。

{
  "_comment": "本番環境用の設定ファイル。timeoutの単位はミリ秒",
  "apiEndpoint": "<https://api.example.com/v1>",
  "timeout": 5000
}

配列内で複数のコメントを残したい場合は、末尾に数字を振るなどして重複を避けます。

{
  "_comment1": "retryCountは失敗時の再試行回数",
  "_comment2": "2024年時点で最大5回まで許可",
  "retryCount": 3
}

命名のベストプラクティスとしては、以下の3点を意識すると安全です。

• 先頭にアンダースコアを付け、通常のデータキーと視覚的に区別する
• プロジェクト全体で命名規則(_commentか__noteかなど)を統一する
• キー名に連番や日付を含め、複数コメントが並んでも意味が追えるようにする

テスト用に特定の値や複数行を一時的に無効化(キー名変更)する具体的な手順

JavaScriptのコメントアウトのように「一時的に無効化する」操作も、JSONではキー名を変更することで代用します。パーサーはキー名の中身までは検証しないため、プレフィックスを付けるだけで実質的に読み込み対象から外せます。

{
  "featureFlags": {
    "enableNewUI": true,
    "_disabled_enableBetaSearch": false,
    "enableDarkMode": true
  }
}

手順は次の通りです。

1. 無効化したいキーの先頭に_disabled_などの接頭辞を付ける
2. 読み込み側のコードで、その接頭辞が付いたキーを無視するように実装するか、単純に未参照のまま放置する
3. 再度有効化する際は接頭辞を外すだけで元の値に戻せる

const config = {
  "enableNewUI": true,
  "_disabled_enableBetaSearch": false,
  "enableDarkMode": true
};

// 接頭辞が付いていないキーだけを有効な設定として扱う
const activeFlags = Object.fromEntries(
  Object.entries(config).filter(([key]) => !key.startsWith("_disabled_"))
);

console.log(activeFlags);
// { enableNewUI: true, enableDarkMode: true }

この方法は、値を削除せずに履歴として残しておきたいテストやデバッグの場面で特に有効です。

独自プロパティ追加時の注意点!JSON Schemaバリデーションや他システムへの影響

ダミーキーによるコメント代用は便利な反面、副作用があることも理解しておく必要があります。特に注意すべきはJSON Schema(JSONデータの構造や型を検証するための仕様)を使ったバリデーションです。additionalProperties: falseが設定されているスキーマでは、_commentのような独自キーがあるだけでバリデーションエラーになります。

{
  "type": "object",
  "properties": {
    "apiEndpoint": { "type": "string" },
    "timeout": { "type": "number" }
  },
  "additionalProperties": false
}

上記のスキーマに対して、先ほどの_commentキー付きJSONを検証すると、未定義プロパティとして弾かれます。対策としては以下が考えられます。

• スキーマ側で_commentのようなキーを明示的に許可するプロパティとして定義する
• コメント用のキーは本番デプロイ前のビルドステップで除去し、スキーマ検証はコメントを取り除いた後のデータに対して行う
• 外部APIやライブラリにそのままJSONを渡す場合、独自キーが原因で想定外のフィールドとして処理されないか事前に確認する

ダミーキー方式は手軽ですが、あくまで「他システムに影響を与えない範囲で使う」ことが前提だと意識しておきましょう。

JSONC・JSON5とは?コメントが書ける拡張フォーマット

ダミーキーによる代用に限界を感じたら、コメント記述そのものを許可する拡張フォーマットの利用を検討する段階です。ここでは代表的な2つの拡張フォーマット「JSONC」と「JSON5」の特徴と、実務での使い分け方を解説します。

JSONCの特徴と「.jsonc」拡張子の使いどころ

JSONC(JSON with Comments)は、標準のJSON構文に//や/* */によるコメントを追加できるようにした拡張フォーマットです。Visual Studio Codeの設定ファイル(settings.jsonやtsconfig.jsonなど)で採用されていることで広く知られています。

{
  // エディタの基本設定
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  /*
   * 拡張機能ごとの個別設定
   * チーム内で変更する場合はSlackで共有すること
   */
  "eslint.enable": true
}

JSONCは末尾カンマ(trailing comma)を許容する実装が多い点もJSONとの違いです。ただし、これはJSONC自体の公式仕様として厳密に定義されているわけではなく、VS Codeなどのパーサー実装依存であることに注意してください。

拡張子は.jsoncを使うのが基本です。ファイル名だけで「このファイルはコメント付きの設定ファイルである」と明示でき、エディタもシンタックスハイライトやコメント補完を正しく適用できます。設定ファイルやビルドツールの構成ファイルなど、人間が読み書きする頻度が高いファイルに向いています。

JSON5でコメントが便利機能とJSONCとの違い

JSON5は、JSONCよりもさらに踏み込んでJavaScriptのオブジェクトリテラルに近い書き味を実現した拡張フォーマットです。コメントに加えて、以下のような機能が使えます。

{
  // クォートなしのキーが使える
  name: "sample-app",
  version: "1.0.0",

  // シングルクォート文字列も使える
  description: 'JSON5のサンプル設定',

  // 末尾カンマが正式にOK
  keywords: [
    "json5",
    "config",
  ],

  // 16進数や先頭ドットの数値表記も可能
  maxRetries: 0x0A,
  ratio: .75,
}

JSONCとJSON5の大きな違いは、JSON5が「構文自体を大幅に緩和した独立フォーマット」であるのに対し、JSONCは「JSONにコメントだけを足した最小限の拡張」である点です。JSON5はNode.jsのpackage.json5や一部のビルドツール設定で使われますが、標準のJSON.parse()では読み込めないため、専用のパーサーライブラリを導入する必要があります。

// JSON5を読み込む場合はパーサーが必須
const JSON5 = require("json5");
const fs = require("fs");

const config = JSON5.parse(fs.readFileSync("./config.json5", "utf-8"));
console.log(config.name);

JSONC・JSON5を「.json」のまま保存してよいかの判断基準

ここで出る疑問が「拡張子は.jsonのままでJSONCやJSON5の書き方をしてよいか」という点です。結論としては、原則として避けるべきです。理由は次の3つに整理できます。

• 標準のJSON.parse()はコメントを一切許容しないため、拡張子が.jsonのままだと実行時に構文エラーになる
• 拡張子が.jsonのままだと、他の開発者やツールが「純粋なJSONである」と誤認し、意図せずコメントを消してしまう、あるいは非対応パーサーで処理してエラーになる
• CI/CDやリンターの多くは拡張子ベースでパーサーを切り替えるため、実体と拡張子が一致していないと検証が正しく機能しない

判断基準としては、以下のように分けるのが安全です。

エディタが暗黙的に.jsonファイルをJSONCとして解釈してくれるケース(VS Codeの一部設定ファイルなど)もありますが、それはあくまで特定ツールの特別扱いです。汎用性を優先するなら、コメントを使う時点で拡張子も正直に変えておくのが事故を防ぐ最善策です。

YAML・TOMLへの移行と本番環境でのビルド・CI/CD自動除去対策

拡張フォーマットでも要件を満たせない場合、そもそもJSON以外のフォーマットへの移行や、コメント付きファイルを本番用に自動変換する仕組みづくりが選択肢になります。ここでは仕様の違いと具体的な構築手順を見ていきます。

コメントが使えるYAML(#)やTOMLとの仕様比較とJSONからの変換方法

YAMLとTOMLはどちらも標準仕様の中にコメント構文を持つデータフォーマットです。YAMLは#、TOMLも同じく#でコメントを書けます。

# アプリケーションの基本設定
appName: sample-app
timeout: 5000 # ミリ秒単位

database:
  host: localhost
  port: 5432

# アプリケーションの基本設定
appName = "sample-app"
timeout = 5000 # ミリ秒単位

[database]
host = "localhost"
port = 5432

JSONとの主な違いは以下の通りです。

JSONからYAMLへの変換はNode.js環境であればjs-yamlのようなライブラリで簡単に行えます。

const yaml = require("js-yaml");
const fs = require("fs");

const jsonData = JSON.parse(fs.readFileSync("./config.json", "utf-8"));
const yamlStr = yaml.dump(jsonData);

fs.writeFileSync("./config.yaml", yamlStr);
console.log("config.yamlを生成しました");

GitHub - nodeca/js-yaml: JavaScript YAML parser and dumper. Very fast.

JavaScript YAML parser and dumper. Very fast. Contribute to nodeca/js-yaml development by creating an account on GitHub.

github.com

API通信のペイロードなど「機械同士のやり取り」にはJSONを維持し、人間が読み書きする設定ファイルはYAML・TOMLに寄せるという住み分けが現実的です。

webpackやプリプロセッサを使って本番ビルド時にコメントを自動除去する構築手順

開発中はJSONCやJSON5でコメントを書きつつ、本番環境には純粋なJSONだけを配置したい場合、ビルド時に自動変換する仕組みを組み込みます。以下はNode.jsスクリプトで.jsoncをコメントなしの.jsonに変換する例です。

// build/strip-json-comments.js
const fs = require("fs");
const path = require("path");
const stripJsonComments = require("strip-json-comments");

const srcPath = path.resolve(__dirname, "../config/app.jsonc");
const distPath = path.resolve(__dirname, "../dist/app.json");

const raw = fs.readFileSync(srcPath, "utf-8");
const cleaned = stripJsonComments(raw);

// 変換後、正しいJSONかどうかを必ず検証してから書き出す
const parsed = JSON.parse(cleaned);
fs.writeFileSync(distPath, JSON.stringify(parsed, null, 2));

console.log("app.jsoncからコメントを除去し、dist/app.jsonに出力しました");

package.jsonのビルドスクリプトに組み込めば、開発者は.jsoncを編集するだけで、本番用の純粋な.jsonが自動生成されます。

{
  "scripts": {
    "build:config": "node build/strip-json-comments.js",
    "build": "npm run build:config && webpack --mode production"
  }
}

webpackを使う場合は、raw-loaderなどでJSONCファイルを文字列として読み込み、同様にコメント除去処理を通してからJSONとして扱うプラグインを組み込む方法も有効です。重要なのは「コメント付きファイルはソースコードの一部として管理し、本番デプロイ物には含めない」という設計方針を徹底することです。

あわせて読みたい

Webpackは本当に開発終了したのか？現状と後継候補（Vite・Turbopack）への移行手順まで全まとめ

Webpackの開発終了に関する真相を公式情報やGitHubの状況をもとに徹底解説します。今後のサポートやセキュリティ面の懸念点、利用し続けるリスクを明確にし、代替ツール（Vite、Turbopack、esbuild）の特徴や違いを比較。また、移行手順や既存プロジェクトへの影響、最適な技術選定のポイントについても紹介

watashi.xyz

2025.04.23

CI/CDでの構文バリデーションチェックと事故を防ぐチーム内運用ルールの作成

ビルドの自動化だけでは、人的ミス(コメント除去前のファイルを誤ってデプロイするなど)を完全には防げません。CI/CDパイプラインに構文チェックを組み込み、事故を機械的に検知する仕組みが必要です。

# .github/workflows/validate-json.yml
name: Validate JSON

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: npm ci
      - name: Validate dist JSON files
        run: |
          for file in dist/*.json; do
            node -e "JSON.parse(require('fs').readFileSync('$file', 'utf-8'))" || exit 1
          done

このワークフローは、dist配下に出力された.jsonファイルが本当にコメントなしの正しいJSONになっているかを、デプロイ前に自動検証します。

チーム運用ルールとしては、以下を明文化しておくと事故を減らせます。

• コメントを書いてよいのは.jsonc/.json5ファイルのみとし、.jsonファイルへの直接編集は禁止する
• ビルド成果物である.jsonファイルは手動編集せず、必ずソースの.jsoncから再生成する
• CIの構文バリデーションが失敗した状態ではマージ・デプロイを許可しない設定にする(ブランチ保護ルールとの連携)
• 新規メンバー向けのオンボーディング資料に、コメント付きファイルと本番ファイルの管理フローを明記する

こうした自動化とルール整備をセットで行うことで、「コメントを書きたいがJSONでは書けない」というジレンマを、開発体験を落とさずに解消できます。

よくある質問(FAQ)

まとめ

JSONにコメントが書けないのは仕様上の欠陥ではなく、RFC 8259・ECMA-404に基づく意図的な設計です。この記事のポイントを整理します。

まずは手元の設定ファイルを.jsoncに切り替えるところから始め、本番デプロイ前にコメントを自動除去・検証するCI/CDフローを導入してみましょう。

あわせて読みたい

「GraphQLは流行らない？」REST全盛期から現在までの背景とメリット・デメリット徹底解説

GraphQLは便利なAPI設計手法として注目されつつも、「流行らない」と言われることがあります。本記事では、GraphQLの仕組みや誕生の背景、RESTとの違いを丁寧に解説し、なぜ普及しにくいのかをいろんな観点から整理します。また、メリット・デメリット、プロジェクトに向いているケース・代替技術まで幅広く紹介します。

watashi.xyz

2025.07.26

コストパフォーマンスに優れた高性能なレンタルサーバー