---
title: "JSONにコメントは書ける？コメントアウトできない理由とJSONC・JSON5の書き方・言語別の読み込み実装【2026年版】"
url: "https://www.issoh.co.jp/tech/details/17784/"
published: 2026-09-24
updated: 2026-10-02
categories: ["開発"]
publisher: "株式会社一創"
---

# JSONにコメントは書ける？コメントアウトできない理由とJSONC・JSON5の書き方・言語別の読み込み実装【2026年版】

JSONには、`//`や`/* */`でコメントアウトする文法がありません。設定ファイルに一行メモを残したいだけでも、標準のパーサはそこでエラーを返します。JSONにコメントを書きたいなら、JSONCやJSON5といった拡張形式へファイルごと切り替え、読み込む側もそれに対応したパーサへ替える必要がある。この記事では、書けない根拠を仕様の文法から示したうえで、4つの代替手段の比較、ファイル別のコメント可否、VS Codeの設定、Node.js・Python・Goでの読み込みコード、CIでの構文チェック、そしてAPIの送受信には持ち込まないという判断基準までを実装者向けにまとめます。

## まとめ｜JSONにコメントは書けず、書くならJSONCへ形式ごと変える判断

標準のJSONにコメントを書く方法はありません。RFC 8259とECMA-404の文法に存在しないため、書けば構文エラーです。人が編集する設定ファイルに注記を残したいなら、拡張子を`.jsonc`にしてJSONCとして扱い、読み込み側をjsonc-parserやhujsonのような対応パーサへ替えるのが第一候補になります。末尾カンマやクォート無しのキーまで欲しいならJSON5を選ぶ。

避けるべきは2つ。`"_comment"`のようなコメント用キーを本番のデータに混ぜること、そしてコメントつきJSONをAPIのリクエストやレスポンスに流すことです。前者は厳格な検証で弾かれ、後者は受け手の言語ごとにパーサ対応を強いる。コメントを許すのは人が書いて特定のツールが読む設定ファイルまで、と線を引いてください。ツールが名前を決めているファイルは、そのツールの公式ドキュメントがコメントを許すかどうかで判断します。

## JSONでコメントアウトできない理由｜RFC 8259の文法とパーサの挙動

「書けない」は慣習ではなく仕様の文法から来ています。根拠と、実際に書いたときの壊れ方を順に確認します。

### 仕様の事実｜RFC 8259とECMA-404の文法にコメント記号は無い

JSONの仕様は[IETFのRFC 8259（STD 90）](https://www.rfc-editor.org/info/rfc8259/)と[Ecma InternationalのECMA-404](https://ecma-international.org/publications-and-standards/standards/ecma-404/)の2本です。どちらも文法として定義するのは、オブジェクト・配列・文字列・数値・`true`・`false`・`null`と、その間に置ける空白（スペース・タブ・改行・復帰）だけ。コメントを表す記号はどこにも出てきません。

値の型そのものは6種類に限られ、その一覧は[JSONのデータ型とTypeScriptでの型定義](https://www.issoh.co.jp/tech/details/2682/)で整理しています。コメントはこのどれにも当たらないため、仕様に沿ったパーサは例外なく拒否します。

### エラーの出方｜Pythonのjson.loadsが2行目のコメントで止まる例

標準ライブラリで読むと、コメントの位置で即座に失敗します。次のコードはPython 3.14系で実行した結果をそのまま載せたものです。

```
import json

src = """{
  // 接続先
  "host": "db.local",
  "port": 5432
}"""
json.loads(src)
# json.decoder.JSONDecodeError:
#   Expecting property name enclosed in double quotes: line 2 column 3 (char 4)
```

エラー文は「コメントがある」とは言わず「キーのダブルクォートが来るはずの場所に別の文字がある」と言います。JavaScriptの`JSON.parse`も同じくトークン単位でしか報告しません。設定ファイルが急に読めなくなったとき、誰かが足したコメントが原因だと気付くまで時間がかかるのはこのためです。

## コメントを書く4つの方法｜JSONC・JSON5・コメント用キー・YAMLの比較

選択肢は、JSONを拡張した形式に移る2通り、JSONのままキーで代用する1通り、別形式に移る1通りです。

### 4方式の比較表｜コメント可否と末尾カンマの扱いと読み込み側の負担

| 方式      | コメント       | 末尾カンマ   | 読み込み側       | 向く用途        |
| ------- | ---------- | ------- | ----------- | ----------- |
| JSONC   | //・/\* \*/ | 実装次第    | 対応パーサが必要    | エディタやCLIの設定 |
| JSON5   | //・/\* \*/ | 可       | json5パーサが必要 | 手書きが多い設定    |
| コメント用キー | 文字列の値で代用   | 不可      | 標準パーサのまま    | 一時的なメモ      |
| YAML    | #          | 記号自体が不要 | YAMLパーサが必要  | CI定義や大きな設定  |

実務でまず検討するのはJSONCです。JSONとの差がコメントだけなので、既存ファイルの中身を書き換えずに済みます。JSON5は表現の自由度が高いぶん、JSONに戻すときに直す箇所が増える。YAMLは構造ごと書き直しになるため、コメントのためだけに移る理由にはなりません。

### JSONCの書き方｜VS Codeのsettings.jsonと同じ二種類のコメント記法

JSONC（JSON with Comments）は、JSONに行コメントとブロックコメントだけを足した形式です。[VS Codeの公式ドキュメント](https://code.visualstudio.com/docs/languages/json)は、`settings.json`・`tasks.json`・`launch.json`をこのモードで扱うと明記しています。

```
{
  // 接続先（本番はhostだけ差し替える）
  "host": "db.local",
  "port": 5432, /* PostgreSQLの既定ポート */
  "tags": ["api", "batch"]
}
```

仕様書は[jsonc.org](https://jsonc.org/)がドラフトとして公開しており、推奨拡張子は`.jsonc`です。注意すべきは末尾カンマの扱いで、このドラフトは末尾カンマを必須要件にしていません。参照実装のjsonc-parserが既定では許さないためです。一方のVS Codeは受け付けつつ警告を出す。どちらの挙動に合わせるかがツールごとに割れるので、JSONCでは末尾カンマを書かない運用に揃えるのが安全です。

### JSON5の書き方｜末尾カンマとクォート無しキーまで許す拡張仕様

[Standard JSON5 1.0.0](https://spec.json5.org/)（2018年3月）は、ECMAScript 5.1の記法をJSONへ持ち込んだ仕様です。コメントに加えて、末尾カンマ・シングルクォートの文字列・クォート無しのキー・16進数・`Infinity`や`NaN`まで書けます。

```
{
  // キーのクォートを省略できる
  host: 'db.local',
  port: 0x1538, // 16進数で5432
  retry: [1, 2, 4,],
}
```

npmの`json5`パッケージは2.2.3（2022年12月公開）が2026年10月時点の最新です。手書きのしやすさはJSONCより上ですが、この書き方をしたファイルは標準のJSONパーサでは一行目から読めません。JSONへ戻す可能性があるなら、使う拡張はコメントだけに絞ってJSONCを選んでください。

### コメント用キーの落とし穴｜\_commentと重複キーが検証で壊れる理由

形式を変えずに済ませる手として、`"_comment": "説明"`のように値でメモを持たせる方法があります。標準パーサのまま読めるのが唯一の利点で、代わりにその文字列はデータとして流れます。`additionalProperties: false`で余分なキーを禁じたスキーマ検証に通すと、そこで弾かれる。

同じキーを2回書いて1回目を注記に使う方法は、さらに危ういものです。RFC 8259はキーが一意であるべきとしつつ、重複時の扱いを定めていません。[Pythonのjsonモジュールの公式ドキュメント](https://docs.python.org/3/library/json.html)は、例外を出さず最後の値を採ると書いています。どちらを採るかはパーサ次第で、読む側が変わった瞬間に注記が設定値として効くおそれがある。本番のデータでは使わないでください。

## ファイル別のコメント可否｜設定ファイルの読み込みツールと公式仕様による判断

「JSONにコメントを書けるか」は、形式ではなくそのファイルを読むツールで決まります。拡張子が`.json`でも読み手がJSONC対応なら書けますし、逆に読み手が1つでも標準パーサなら書けません。devcontainer.json・deno.jsonc・package.jsonなど、代表的な設定ファイルのコメント可否を公式ドキュメントの記述で分けると次のとおりです（2026年10月時点）。

| ファイル                  | コメント | 根拠          |
| --------------------- | ---- | ----------- |
| VS Codeのsettings.json | 書ける  | JSONCモードで扱う |
| devcontainer.json     | 書ける  | 仕様がJSONCと明記 |
| deno.jsonc            | 書ける  | 末尾カンマも可     |
| package.json          | 書けない | 実際のJSONが必須  |

[Development Container Specification](https://containers.dev/implementors/spec/)は、メタデータを「JSON with Comments」のファイルである`devcontainer.json`に保存できると書いています。[Denoの設定ドキュメント](https://docs.deno.com/runtime/fundamentals/configuration/)は`.json`と`.jsonc`の両方を受け付け、`deno.jsonc`ならコメントと末尾カンマを足せると説明しています。

反対に[npmのpackage.jsonリファレンス](https://docs.npmjs.com/cli/v11/configuring-npm/package-json)は、このファイルが「JavaScriptのオブジェクトリテラルではなく実際のJSON」でなければならないと定めています。表に無いファイルも同じ手順で判断できます。読み手のツールの公式ドキュメントを開き、JSON with Commentsや`.jsonc`への言及があるかを確認してください。言及が見つからないなら、コメントは書かない側に倒します。

## 言語別の読み込み実装｜Node.js・Python・GoでJSONCをパースする手順

コメントを書けるようにしたら、読む側も替えます。3言語それぞれで、依存を1つ足すだけで済む方法を示します。

### Node.jsの実装｜jsonc-parserのparseでエラー位置まで取る方法

[jsonc-parser](https://github.com/microsoft/node-jsonc-parser)はVS Codeと同じ系統のパーサで、npmの最新は3.3.1です。`parse`は壊れた入力にも可能な限り値を返す寛容な設計なので、エラー配列を必ず確認します。

```
// npm install jsonc-parser
const { readFileSync } = require('node:fs');
const { parse, printParseErrorCode } = require('jsonc-parser');

const text = readFileSync('config.jsonc', 'utf8');
const errors = [];
const config = parse(text, errors, { allowTrailingComma: false });

if (errors.length > 0) {
  for (const e of errors) {
    console.error(printParseErrorCode(e.error), 'offset', e.offset);
  }
  process.exit(1);
}
console.log(config.host, config.port);
```

エラーを見ずに`config`を使うと、閉じ括弧が欠けたファイルでも途中までの値で起動してしまいます。コメントを消して標準の`JSON.parse`へ渡したいだけなら、[strip-json-comments](https://github.com/sindresorhus/strip-json-comments)（5.0.3・ESM専用）も選べます。こちらは`trailingCommas`オプションが既定で無効です。

### Pythonの実装｜json5パッケージのloadsで標準jsonと同じ形に読む

Pythonの標準`json`にはコメントを読む設定がありません。PyPIの`json5`パッケージ（2026年10月時点で0.15.0）を入れると、標準と同じ関数名で読めます。JSON5はJSONCの上位互換なので、JSONCのファイルもそのまま通る。

```
# pip install json5
import json5

with open("config.jsonc", encoding="utf-8") as f:
    config = json5.load(f)

print(config["host"], config["port"])
```

注意点は、JSON5として許される記法も黙って通すことです。シングルクォートやクォート無しのキーが混ざっても通るため、JSONCの範囲に留めたいなら、CIで別途JSONCパーサに掛けて記法を縛ります。

### Goの実装｜hujsonのStandardizeで標準JSONに戻してから読む

Goでは[tailscale/hujson](https://pkg.go.dev/github.com/tailscale/hujson)が定番です。コメントと末尾カンマを許すJWCCという形式を扱い、`Standardize`でRFC 8259準拠のJSONへ変換してから標準の`encoding/json`に渡します。

```
// go get github.com/tailscale/hujson
package main

import (
	"encoding/json"
	"fmt"
	"os"

	"github.com/tailscale/hujson"
)

type Config struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

func main() {
	b, err := os.ReadFile("config.hujson")
	if err != nil {
		panic(err)
	}
	std, err := hujson.Standardize(b)
	if err != nil {
		panic(err)
	}
	var c Config
	if err := json.Unmarshal(std, &c); err != nil {
		panic(err)
	}
	fmt.Println(c.Host, c.Port)
}
```

`Standardize`はコメントを消すのではなく空白に置き換えるため、行番号とバイト位置が元のファイルと一致します。`Unmarshal`のエラーが指す位置をそのまま元ファイルで探せるのが、この方式を選ぶ理由です。サイズを詰めたいときは`Minimize`を使います。hujsonにはタグ付きの版が無く、2026年7月の疑似版が最新です。

標準JSONへ戻す工程を挟んでおくと、後段のツールはコメントの存在を知らずに済みます。たとえば[jqコマンドでJSONを抽出・整形する手順](https://www.issoh.co.jp/tech/details/17923/)に渡す前にも、この変換を1段入れておけば、jq側の対応状況を気にせず加工できます。

## エディタとスキーマの設定｜VS Codeのjsonc割り当てと$commentの記述

ファイルを書く側の環境も揃えておかないと、エディタが赤線を引き続けます。

### VS Code｜files.associationsで拡張子とjsoncの関連付け

拡張子が`.jsonc`ならVS Codeは自動でJSON with Commentsとして開きます。既存の`.json`のままコメントを許したいファイルがあれば、`files.associations`でパターンごとに割り当てます。

```
{
  "files.associations": {
    "*.hujson": "jsonc",
    "**/config/*.json": "jsonc"
  }
}
```

これはエディタの表示を変えるだけで、アプリが読むときのパーサは変わりません。チームで揃えるなら、この設定をリポジトリの`.vscode/settings.json`に置くか、開発環境の定義に含めます。[Dev Containerで開発環境の設定を統一する方法](https://www.issoh.co.jp/tech/details/3728/)を使えば、拡張機能と一緒に配れます。

### JSON Schemaの$comment｜仕様内でスキーマに注記を残す正規の手段

スキーマファイルに限っては、仕様の中にコメントの置き場があります。[JSON Schemaの$commentキーワード](https://json-schema.org/understanding-json-schema/reference/comments)はDraft 7で追加され、値は文字列、検証には一切影響しません。

```
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$comment": "portは社内規約で1024以上に限定",
  "type": "object",
  "properties": {
    "port": { "type": "integer", "minimum": 1024 }
  }
}
```

公式の解説は、`$comment`を将来スキーマを編集する人への備忘録と位置付け、利用者向けの説明には`description`を使うよう求めています。実装が`$comment`を消してもよいとされているためです。スキーマの書き方全体は[JSON Schemaの書き方とDraft 2020-12の実装](https://www.issoh.co.jp/tech/details/16289/)にまとめています。

## コメント付きJSONの採用条件｜設定ファイル限定でAPIには流さない判断

ここまでの手段は、どこで使うかを誤ると保守の負債になります。判断を言い切ります。

### 採用する場面｜人が編集して単一のツールが読み込む設定ファイルの条件

JSONCを採用してよいのは、次の条件をすべて満たすファイルです。

- 人が手で編集し、設定値の理由を残す必要がある
- 読むプログラムが1種類に決まっていて、パーサを替えられる
- リポジトリで管理し、変更がレビューを通る

アプリの設定ファイル、ローカル開発用の定義、CLIツールの設定がこれに当たります。条件を1つでも外れるなら、コメントはREADMEか`$comment`へ逃がしてください。

### 見送る場面｜APIの送受信とデータ交換に拡張JSONを流す失敗

APIのリクエストとレスポンス、システム間で受け渡すデータファイルには、コメントを入れません。`application/json`を名乗る以上、受け手はRFC 8259準拠を前提に標準パーサで読みます。送信側だけJSONCにすると、相手の言語と実装の数だけ読み込み失敗が起きる。受け手が複数社にまたがる連携では、これが障害の問い合わせとして返ってきます。

形式の使い分けは[application/jsonとフォーム形式の違いと使い分け](https://www.issoh.co.jp/tech/details/4610/)で、仕様の意図を伝えたいときの応答設計は[APIエラーレスポンスの設計手順](https://www.issoh.co.jp/tech/details/17229/)で扱っています。項目の意味を相手に伝えたいなら、ペイロードに注記を混ぜずOpenAPIやJSON Schemaの`description`を使い、仕様書側に記述してください。仕様書の書き方は[OpenAPIの仕様書（YAML/JSON）の書き方](https://www.issoh.co.jp/tech/details/10408/)が参考になります。連携先ごとに形式がばらついて困っている場合は、[API開発・システム連携の受託開発](https://www.issoh.co.jp/service/system/api/)で仕様の整理から相談を受けています。

### 移行の手順｜既存の.jsonにコメントを足すときに踏む4つの順序

動いている設定ファイルへ後からコメントを足すときは、読み込み側を先に替えます。

1. 読み込みコードをJSONC対応パーサへ替え、コメントの無い現行ファイルで動作を確認する
2. 拡張子を`.jsonc`へ変更し、参照している箇所のパスを直す
3. CIに構文チェックを足し、末尾カンマや未対応の記法を弾く
4. 最後にコメントを書き込む

順序を逆にしてコメントから足すと、読み込み側を替えるまでの間は起動できません。拡張子を変えられないファイル（ツール側が名前を決めているもの）は、そのツールがコメントを許しているかを公式ドキュメントで確かめてから書きます。

### CIの構文チェック｜jsonc-parserで末尾カンマと記法違反を落とすスクリプト

移行手順の3番目は、Node.jsの小さなスクリプトで実現できます。引数に渡した`.jsonc`ファイルをすべて読み、1件でもエラーがあれば終了コード1で落とします。

```
// check-jsonc.js（実行例: node check-jsonc.js config/*.jsonc）
const { readFileSync } = require('node:fs');
const { parse, printParseErrorCode } = require('jsonc-parser');

let failed = false;
for (const file of process.argv.slice(2)) {
  const errors = [];
  parse(readFileSync(file, 'utf8'), errors, { allowTrailingComma: false });
  for (const e of errors) {
    console.error(`${file}: ${printParseErrorCode(e.error)} at offset ${e.offset}`);
    failed = true;
  }
}
process.exit(failed ? 1 : 0);
```

`allowTrailingComma: false`を指定しているため、VS Codeでは警告止まりの末尾カンマもここで止まります。エディタとCIで判定を揃えておくと、PythonやGoなど別の言語から同じファイルを読む場合にも記法のずれが起きません。

## よくある質問

JSONのコメントアウトについて、検索で多い質問に答えます。

### JSONでコメントアウトする書き方はありますか？

標準のJSONにはありません。RFC 8259とECMA-404の文法にコメントが無いため、`//`も`/* */`も`#`も構文エラーになります。コメントを書くには、ファイルをJSONCかJSON5として扱い、読み込み側を対応パーサへ替える必要がある。形式を変えられない場合は、別ファイルのREADMEに説明を置くか、JSON Schemaを使っているなら`$comment`に書くのが現実的な代替です。

### JSONCとJSON5の違いは何ですか？

JSONCはJSONにコメントだけを足した形式で、JSON5はコメントに加えて末尾カンマ、シングルクォート、クォート無しのキー、16進数なども許す形式です。JSONCはコメントを消せば標準JSONに戻りますが、JSON5は書き方次第で戻すのに手直しが要る。JSON5のパーサはJSONCのファイルも読めます。既存のJSONにメモを足したいだけならJSONC、手書きの量が多い設定ならJSON5が向きます。

### package.jsonにコメントを書けますか？

書かないでください。npmの公式リファレンスは`package.json`を実際のJSONでなければならないと定めています。npmやパッケージマネージャ、ビルドツールなど複数のプログラムが読むファイルで、コメント非対応の読み手が1つでもあれば壊れます。これはこの記事の採用条件のうち「読むプログラムが1種類」を満たさない典型例です。説明を残したいなら、scriptsの意図はREADMEに書き、依存の固定理由はコミットメッセージやプルリクエストに残すのが安全です。

### VS Codeでコメントに赤線が出るのはなぜですか？

ファイルがJSONモードで開かれているからです。拡張子が`.json`のファイルは、VS Codeの設定ファイルなど一部を除いて標準JSONとして検証されます。画面右下の言語モード表示から「JSON with Comments」へ切り替えるか、`files.associations`でパターンを`jsonc`に割り当てると消えます。ただし変わるのはエディタの表示だけです。アプリ側のパーサが対応していなければ、実行時の読み込みは失敗します。

### JSONのコメントを消して標準JSONに変換するには？

対応ライブラリの変換関数を使います。Node.jsなら`strip-json-comments`かjsonc-parserの`stripComments`、Goならhujsonの`Standardize`が該当します。正規表現で`//`以降を消す自作処理は避けてください。`"https://example.com"`のように文字列の中にある`//`まで消してしまい、URLを含む設定が壊れます。文字列の内外を判定できるパーサに任せるのが確実です。

## 関連記事

- [JSON Schemaとは？JSONの構造を検証する書き方とDraft 2020-12の実装を実装者目線で解説【2026年版】](https://www.issoh.co.jp/tech/details/16289/)
- [JSONの型定義とデータ型一覧｜6つの型とTypeScriptで型安全に扱う方法](https://www.issoh.co.jp/tech/details/2682/)
- [jqコマンドの使い方｜JSONの抽出・整形・CSV変換を実行例で覚える【1.8.2対応】](https://www.issoh.co.jp/tech/details/17923/)
- [application/x-www-form-urlencoded と application/json の違い｜使い分けと変換方法を解説](https://www.issoh.co.jp/tech/details/4610/)
- [APIエラーレスポンス設計とは？コード体系・リトライ判断・漏洩防止の実装手順](https://www.issoh.co.jp/tech/details/17229/)
- [Dev Container（devcontainer）のメリットとは｜Dockerで開発環境を統一する仕組みと設定【2026年版】](https://www.issoh.co.jp/tech/details/3728/)

---

出典: [JSONにコメントは書ける？コメントアウトできない理由とJSONC・JSON5の書き方・言語別の読み込み実装【2026年版】](<https://www.issoh.co.jp/tech/details/17784/>)（株式会社一創）