Bisakah JSON memiliki komentar
Intinya: RFC 8259 tidak memiliki sintaks komentar, sehingga // dan komentar blok membuat JSON.parse melempar error. Gunakan JSON5 atau JSONC, field _comment, description pada Schema, atau YAML sebagai gantinya.
Intinya: jangan pernah menaruh komentar di JSON standar; gunakan JSONC atau JSON5 untuk konfigurasi lokal yang hanya diedit manusia, pindahkan penjelasan ke description JSON Schema ketika berkas melintasi sistem, dan beralih ke YAML atau TOML begitu volume anotasi bertambah.
Tidak.
Parser apa pun yang sesuai standar menolak ini:
{
"port": 8080 // local development only
}
Chrome melaporkan SyntaxError: Unexpected token }. Parser berhenti karena menemui /, yang tidak dapat memulai nilai JSON apa pun.
Mengapa spesifikasi sengaja menghilangkan komentar
RFC 8259 mendefinisikan enam nilai: objek, array, angka, string, true/false, null. Tidak ada produksi komentar.
Komentar pernah diusulkan di awal dan ditolak dengan alasan konkret: begitu komentar menjadi legal, seseorang memakainya untuk membawa direktif — include bersyarat, variabel template — dan setiap parser menumbuhkan dialeknya sendiri. Interoperabilitas rusak pada lompatan pertama. JSON sengaja hanya berisi data (data-only), tanpa apa pun yang dapat dieksekusi di dalamnya.
Empat cara menyimpan catatan Anda
1. Gunakan superset. JSON5 dan JSONC menerima kedua gaya komentar. settings.json dan tsconfig.json VS Code adalah JSONC.
Biayanya nyata: JSON.parse tetap menolaknya, dan API, pipeline log serta message queue biasanya hanya menerima JSON standar. Komentar Anda diam-diam dibuang atau melempar error di suatu tempat di hilir.
2. Taruh catatan di dalam data.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Berfungsi di mana saja, tetapi mencemari model: setiap konsumen harus mengetahui key mana yang diabaikan, dan definisi tipe Anda bertambah field yang sebenarnya bukan data.
3. Gunakan description pada Schema. description ditujukan untuk manusia dan alat. Validator menampilkannya, editor menampilkannya saat hover, dan ia tidak pernah masuk ke payload. Ini satu-satunya opsi yang bertahan dalam pemeliharaan jangka panjang tanpa merusak kompatibilitas.
4. Ubah format berkas. Jika berkas itu ada untuk diedit dengan tangan, YAML atau TOML mendukung komentar secara native. Memerangi JSON di sini hanya membuang usaha.
Memilih
| Situasi | Jawaban |
|---|---|
| Dikirim ke sistem lain, melalui API atau queue | Tanpa komentar; dokumentasikan di Schema atau dokumen eksternal |
| Konfigurasi yang hanya dibaca manusia dan editor | JSONC, dengan ekstensi .jsonc |
| Membutuhkan perkakas universal dan penjelasan inline | JSON standar plus description pada Schema |
| Konfigurasi panjang dengan banyak anotasi | Beralih ke YAML |
FAQ
Mengapa field _comment mencemari model?
Karena ia menjadi bagian dari data. Setiap konsumen harus mengetahui key mana yang diabaikan, dan definisi tipe bertambah field yang sebenarnya bukan data bisnis.
Haruskah penjelasan disimpan di description JSON Schema?
Ya. description tetap di luar payload, sementara validator menampilkannya dan editor menampilkannya saat hover, jadi ini satu-satunya opsi yang bertahan dalam pemeliharaan jangka panjang tanpa merusak kompatibilitas.
Bisakah JSONC atau JSON5 diurai oleh JSON.parse?
Tidak. JSON.parse tetap menolak komentar, dan API, pipeline log serta message queue biasanya hanya menerima JSON standar, sehingga komentar dibuang atau melempar error di suatu tempat di hilir.
Alat
- Parser JSON5 — tempel konfigurasi berkomentar dan lihat struktur hasilnya
- Formatter dan validator JSON — JSON ilegal dilaporkan dengan baris dan kolom, sehingga komentar yang bermasalah menjadi jelas