JSON, TOML, YAML, atau CSON: Memilih Format Konfigurasi

Intinya: gunakan JSON untuk pertukaran mesin, dan pilih TOML atau YAML untuk konfigurasi yang dipelihara manusia sesuai ekosistemnya (YAML untuk Kubernetes dan CI, TOML untuk struktur datar atau tanggal native); beralih ke JSONC hanya ketika Anda tidak yakin apakah pembaca mendukung dialek tersebut.

JSON ada untuk mesin yang bertukar data; file konfigurasi ditulis oleh orang untuk orang. Campurkan keduanya dan Anda mendapatkan config.json yang tidak dapat memuat komentar dan tidak berani dipangkas siapa pun.

1. Mulailah dari dua jenis file yang berbeda

Pertukaran data dan konfigurasi tidak berbagi tujuan yang sama, meskipun orang yang sama sering menulis keduanya di mesin yang sama.

JSON hampir sempurna di kolom kiri: tata bahasa minimal, parser di setiap bahasa, dan tanpa komentar berarti tidak ada masalah "komentar menyimpang dari nilai". Di kolom kanan, kekakuannya murni friksi: tanpa komentar, tanpa koma di akhir, tanpa tanggal, dan teks multi-baris harus diratakan menjadi satu baris dengan \n.

2. Empat kandidat dan sintaksnya

• JSON: didefinisikan oleh RFC 8259 dan ECMA-404, dengan tepat enam tipe nilai: objek, array, string, angka, boolean, dan null. Ia adalah standar pertukaran de facto dan satu-satunya format yang tidak memerlukan keputusan pemilihan.
• TOML: dibuat oleh Tom Preston-Werner, dengan v1.0.0 diterbitkan pada Januari 2021. Tujuan yang dinyatakan adalah format konfigurasi minimal dengan semantik jelas yang memetakan secara tidak ambigu ke hash table. Cargo.toml dan pyproject.toml menggunakannya secara bawaan.
• YAML: spesifikasi saat ini adalah 1.2.2. Indentasi mengekspresikan hierarki, dan ia mendukung komentar, anchor, dan beberapa dokumen. Manifest Kubernetes, GitHub Actions, dan Ansible semuanya bergantung padanya, dengan biaya spesifikasi besar dan perbedaan implementasi.
• CSON: CoffeeScript Object Notation, yang menulis konfigurasi menggunakan literal objek CoffeeScript. config.cson milik Atom menggunakannya. Ia mendukung komentar, kunci tanpa tanda kutip, dan koma di akhir, tetapi ekosistemnya tidak pernah meninggalkan dunia JavaScript.

2.1 Perbandingan kemampuan

Dua sel layak dicatat. TOML tidak memiliki null, yang merupakan kegagalan paling umum saat mengonversi dari JSON. Perilaku "tanggal native" YAML berarti parser 1.1 mengubah 2026-10-31 menjadi objek tanggal secara otomatis, sehingga tipenya bergeser antar bahasa.

3. Komentar: satu kelemahan JSON

Kesimpulan lebih dulu: jika manusia memelihara file dan perlu menjelaskan mengapa sebuah nilai bernilai demikian, jangan gunakan JSON standar.

Ada empat jalur praktis, diurutkan berdasarkan seberapa invasif:

1. Beralih ke JSONC, yaitu JSON standar plus komentar dan koma di akhir. settings.json dan tsconfig.json milik VS Code menggunakannya. Biayanya adalah pembaca harus menggunakan parser yang sadar komentar seperti jsonc-parser; JSON.parse biasa gagal. Detailnya ada di JSON5 dan JSONC: JSON dengan komentar.
2. Pertahankan dokumen sidecar. config.json tetap dapat dibaca mesin, sementara config.md menjelaskan apa arti setiap field dan mengapa nilainya demikian. Keduanya berada di direktori yang sama dan berubah dalam commit yang sama.
3. Letakkan penjelasan di schema. Kata kunci description dan $comment JSON Schema dapat mendokumentasikan field, tetapi schema jarang dikirim bersama konfigurasi runtime, sehingga orang yang membaca konfigurasi mungkin tidak pernah melihatnya.
4. Beralih ke TOML atau YAML, membiarkan format itu sendiri menyediakan komentar yang dipahami setiap parser.

复制{
  // Fixed at 8080: the frontend build script reads this port for its proxy
  "port": 8080,
  // Disable watching to avoid exhausting inodes in CI
  "watch": false
}

JSONC tetap sebuah dialek: ekstensinya tetap .json, tetapi hanya sebagian alat yang memahaminya. Ketika data meninggalkan tim atau melintasi batas layanan, garis antara JSONC dan JSON standar harus didokumentasikan.

4. Tanggal dan string multi-baris: wilayah asli TOML

TOML menaikkan date-time menjadi tipe kelas satu dengan empat varian: offset date-time, local date-time, local date, dan local time. String multi-baris memiliki sintaks khusus yang mempertahankan pemisah baris:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

Informasi yang sama dalam JSON harus menurunkan tanggal menjadi string dan meng-escape pemisah baris:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

Dalam JSON, "created" hanyalah string yang kebetulan tampak seperti tanggal, sehingga informasi tipe harus berada dalam kontrak field: kedua pihak harus setuju bahwa field itu selalu RFC 3339. TOML memberi parser objek tanggal yang sebenarnya tanpa memerlukan kesepakatan verbal.

YAML juga dapat memuat teks multi-baris, tetapi dua gaya bloknya bermakna berbeda: | mempertahankan pemisah baris sementara > melipatnya menjadi spasi. Pilih yang salah dan sebuah alamat atau pernyataan SQL runtuh menjadi satu baris, kesalahan yang sangat sulit ditangkap dalam tinjauan.

5. Angka: perbedaan yang paling terlewat

Spesifikasi JSON tidak memberi batas pada presisi numerik, tetapi RFC 8259 juga memperingatkan bahwa interoperabilitas paling aman ketika angka diperlakukan sebagai double IEEE 754. Di JavaScript, bilangan bulat di atas 2^53 - 1 diam-diam kehilangan presisi:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: the last digit is gone

TOML mengharuskan bilangan bulat 64-bit bertanda ditangani secara lossless dan memunculkan error alih-alih memotong secara diam-diam; float mengikuti binary64 dan mungkin juga inf atau nan. YAML 1.1 membawa beban lama: 1:30 di-parse sebagai 90 (seksagesimal), dan boolean menerima yes, no, on, dan off. Itulah asal "masalah Norwegia" yang klasik, di mana kode negara NO menjadi false.

Untuk uang, jangan pernah mengandalkan floating point dalam format mana pun di atas: gunakan satuan minor bilangan bulat, string, atau tipe desimal basis data. Pemformatan dan presisi dibahas lebih mendalam di batas konversi JSON, YAML, dan XML.

6. Tabel dan penyarangan: batas keras TOML

TOML mengekspresikan penyarangan dengan tabel dan array of tables:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Ia memiliki dua batas keras yang harus Anda ketahui sebelum mengonversi:

• Root dokumen TOML adalah tabel, sehingga dokumen JSON yang tingkat atasnya array (seperti [1, 2, 3]) tidak memiliki representasi TOML yang legal; ia harus dibungkus sebagai {"items": [...]};
• TOML tidak memiliki null, sehingga field null JSON harus dibuang atau diganti dengan string kosong atau nilai sentinel, dengan semantiknya dibebankan kepada konsumen.

YAML adalah kebalikannya: kedalaman penyarangan tak terbatas, dan anchor plus merge key dapat menggunakan kembali fragmen:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Anchor adalah kemampuan khusus YAML dan kerugian yang dijamin dalam konversi: JSON tidak memiliki sintaks referensi, sehingga file yang diperluas bertambah besar dan tidak ada yang mencatat bahwa kedua bagian itu dulu adalah konfigurasi yang sama.

7. Memilih berdasarkan skenario

Satu aturan praktis: biarkan ekosistem memilih format konfigurasi, bukan preferensi pribadi. Menulis Rust berarti Cargo.toml, men-deploy ke Kubernetes berarti YAML, dan membangun ekstensi VS Code berarti JSONC. Hanya dalam proyek baru tanpa batasan ekosistem, "mana yang lebih enak ditulis" menjadi pertanyaan nyata.

8. Batas konversi

Alat konversi menjamin nilainya, tidak pernah komentarnya. Jadi jangan rancang pipeline dua arah di mana "JSON adalah sumber dan YAML adalah artefak build". Entah hasilkan dalam satu arah saja, atau pelihara satu file sumber.

9. Checklist

• [ ] Dokumentasikan jenis file mana menggunakan format mana, dan daftar dialek yang diizinkan;
• [ ] Utamakan TOML atau YAML untuk konfigurasi yang dipelihara manusia, dan JSON untuk pertukaran mesin;
• [ ] Simpan tanggal dalam JSON sebagai string RFC 3339 dan tandai formatnya di schema;
• [ ] Representasikan uang dan bilangan bulat di atas 2^53 sebagai string atau satuan minor, tidak pernah sebagai float;
• [ ] Validasi setiap format di CI dengan parser-nya sendiri, jangan pernah dengan JSON.parse untuk YAML;
• [ ] Migrasi format dalam satu arah saja, dan hapus file lama agar keduanya tidak menyimpang.

FAQ

Mengapa konversi JSON ke TOML gagal pada sebagian field?

TOML tidak memiliki null, dan root dokumen TOML adalah tabel, sehingga field null JSON harus dibuang atau diganti dengan string kosong atau sentinel, dan array tingkat atas harus dibungkus sebagai {"items": [...]}. Komentar, tipe tanggal, dan inf/nan juga hilang saat bergerak ke arah sebaliknya, itulah sebabnya konversi sebaiknya satu arah.

Haruskah saya memelihara dua file konfigurasi dalam format berbeda?

Tidak. Alat konversi menjamin nilainya tetapi tidak pernah komentarnya, sehingga pipeline di mana "JSON adalah sumber dan YAML adalah artefak build" akan menyimpang. Entah hasilkan dalam satu arah saja, atau pelihara satu file sumber dan hapus file lama setelah migrasi.

Bagaimana cara menambahkan komentar ke file konfigurasi JSON?

JSON standar tidak memiliki komentar. Anda dapat beralih ke JSONC (dialek VS Code, dibaca dengan jsonc-parser), memelihara dokumen sidecar yang menjelaskan setiap field, atau beralih ke TOML atau YAML. File yang dikirim ke sistem lain sebaiknya tetap JSON standar, dengan penjelasan berada di dokumentasi atau schema.

TOML atau YAML yang lebih baik untuk konfigurasi aplikasi?

Pilih TOML ketika strukturnya datar, sebagian besar pasangan kunci-nilai, dan tanggal native penting; semantiknya lebih dapat diprediksi dan perbedaan parser lebih kecil. Pilih YAML ketika Anda membutuhkan penyarangan dalam, beberapa dokumen, penggunaan ulang anchor, atau ketika ekosistem target mengutamakan YAML, seperti Kubernetes atau CI. Keduanya mendukung komentar, sehingga pembeda nyatanya adalah kompleksitas struktur dan keterkaitan ekosistem.

Mengapa NO berubah menjadi false di YAML?

YAML 1.1 memperlakukan yes, no, on, off, y, dan n sebagai boolean, sehingga kode negara Norwegia NO di-parse sebagai false. Inilah "masalah Norwegia". Hindari dengan menggunakan implementasi yang mengikuti YAML 1.2, atau dengan memberi tanda kutip pada setiap string yang mungkin disalahartikan.

Apakah CSON masih layak digunakan?

Tidak untuk proyek baru. CSON bergantung pada ekosistem CoffeeScript, memiliki sedikit alat yang terpelihara, dan dukungan editor serta CI yang terbatas; setelah Atom berhenti dipelihara, kasus penggunaannya menyusut lebih jauh. Jika proyek sudah memiliki konfigurasi CSON, jadwalkan migrasi sekali ke JSON, TOML, atau YAML alih-alih menambahkannya lebih banyak.