TOML vs YAML vs JSON — Format Konfigurasi Diurutkan Berdasarkan Seberapa Banyak Mereka Akan Mengganggu Anda

Setiap proyek akhirnya memaksa Anda memilih format konfigurasi. YAML tersebar di mana-mana. JSON lebih tua dari beberapa rekan Anda. TOML muncul lebih baru dengan menaikkan tangan, mengatakan "sebenarnya, saya dirancang untuk hal ini." Ketiganya akan mengecewakan Anda akhirnya. Kegagalan mereka hanya berbeda.

Berikut adalah perbandingan langsung — konfigurasi yang sama, tiga format — diikuti oleh tepatnya kapan masing-masing akan membuat Anda menyesal atas keputusan hidup Anda.

Konfigurasi yang Sama, Tiga Cara

Konfigurasi aplikasi web dasar: nama, port, flag debug, string versi, pengaturan database, asal-usul yang diperbolehkan. Tidak ada hal eksotis. Di sini perbedaan format mulai terlihat.

Bahasa Indonesia: TOML

# App configuration
[app]
name = "my-app"
port = 3000
debug = false
version = "1.2.3"
allowed_origins = ["https://example.com", "https://api.example.com"]

[database]
host = "localhost"
port = 5432
name = "mydb"

YAML

# App configuration
app:
  name: my-app
  port: 3000
  debug: false
  version: "1.2.3"
  allowed_origins:
    - https://example.com
    - https://api.example.com

database:
  host: localhost
  port: 5432
  name: mydb

JSON

{
  "app": {
    "name": "my-app",
    "port": 3000,
    "debug": false,
    "version": "1.2.3",
    "allowed_origins": [
      "https://example.com",
      "https://api.example.com"
    ]
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Secara Singkat

Fitur	Bahasa Indonesia: TOML	YAML	JSON
Komentar	✅ Ya	✅ Ya	❌ Tidak
Inferensi tipe	Ekspresif	Agresif (sering salah)	Ekspresif
Susunan	= ["a", "b"]	- item atau inline	["a", "b"]
Koma di akhir	T/A	T/A	❌ Tidak sah
Konfigurasi yang sangat terdalam	Meningkatkan kebocoran cepat	Dapat dibaca secara kasar	Sangat panjang tetapi jelas
Stabilitas tipe	TOML 1.0 (2021, stabil)	Perbedaan antara versi 1.1 dan 1.2 parser yang acak	Stabil
Dukungan null	❌ Tidak null tipe	✅ Ya (~ atau null)	✅ Ya (null)
Penggunaan umum	Cargo.toml, pyproject.toml	GitHub Actions, k8s, Docker	package.json, tsconfig.json

YAML: Paling Mudah Dibaca Hingga Tidak Lagi

YAML terlihat bagus dalam demo. Konfigurasi datar terasa hampir seperti sastra. Masalah mulai muncul ketika Anda menemui salah satu kasus batasnya — dan pada saat itu file konfigurasi Anda sudah menjadi infrastruktur yang penting.

Masalah Norwegia

Dalam YAML 1.1 — yang masih menjadi default pada sebagian besar parser — nilai-nilai ini semua merupakan boolean: y, n, yes, no, on, off, true, false. Jadi country: NO diproses sebagai country: false. Ini adalah alasan sebenarnya mengapa disebut masalah Norwegia — kode negara Norwegia adalah NO. PyYAML memperbaikinya di versi 6.0 (diluncurkan tahun 2022). SnakeYAML (digunakan oleh banyak alat Java) masih belum sepenuhnya menangani hal ini. Periksa parser Anda sebelum menggunakan nilai bersih no atau yes dalam nilai konfigurasi.

Inferensi Tipe yang Salah Ditebak

Nilai yang tidak dikelilingi tanda kutip dalam YAML akan dikonversi tipe. port: 8080 menjadi bilangan bulat. version: 1.10 menjadi bilangan desimal 1.1 — secara matematis sama, secara semantik salah. Lupa untuk menambahkan kutipan pada string versi dan Anda akan menghabiskan sepuluh menit mempertanyakan mengapa aplikasi Anda berpikir berada di versi v1.1 alih-alih v1.10. Solusi yang membosankan: kutipkan semua yang seharusnya tetap sebagai string. Tapi YAML tidak memaksa Anda untuk melakukannya, sehingga tidak melakukannya.

Indentasi adalah Penentu Berat

Tanda tab tidak sah dalam YAML — tidak disarankan, tidak sah. Campurkan indentasi dua spasi dan empat spasi dalam satu file dan Anda akan mendapatkan kesalahan parsing yang sering menunjuk ke baris yang salah. GitHub Actions adalah sisi paling tajam di sini: blok yang salah indentasi gagal saat berjalan, bukan saat parsing, karena penggunaan workflow hanya memvalidasi sintaks, bukan struktur langkah. Anda akan mendapatkan pesan "nilai tidak terduga" dari tugas CI tanpa petunjuk tentang langkah mana yang rusak, dan Anda akan menghabiskan 20 menit menambahkan output debug sebelum menyadari bahwa masalahnya adalah indentasi dua spasi yang seharusnya empat spasi. run: Jika konfigurasi YAML Anda menjadi kekacauan karena indentasi yang tidak konsisten, maka

Pengaturan YAML akan menormalisasi sebelum Anda mulai memperbaiki masalahnya. TOML: Format yang Benar-Benar Memikirkan Konfigurasi

Tom Preston-Werner (pendiri GitHub) membuat TOML karena dia lelah menulis konfigurasi berbentuk INI dengan perilaku parsing yang tidak konsisten dan konfigurasi YAML yang mengejutkannya. TOML 1.0 diluncurkan pada Januari 2021 setelah bertahun-tahun revisi. Sekarang ini menjadi standar untuk proyek Rust (

), pengemasan Python (Cargo.toml), dan situs Hugo. Spesifikasi stabil, parser konsisten, dan sistem tipe melakukan apa yang Anda harapkan.pyproject.tomlApa yang Diperolehnya

Tidak ada koersi tipe yang mengejutkan.

• selalu merupakan string. version = "1.10" selalu merupakan bilangan bulat. Yang Anda tulis adalah yang Anda dapatkan. port = 3000 Komentar bekerja persis seperti yang Anda harapkan (
• sampai akhir baris), berbeda dengan JSON.# Konfigurasi datar hingga sedikit terdalam dapat dibaca secara nyata, berbeda dengan JSON yang sangat terdalam.
• Sintaks Array-of-Tables

Hambatan utama TOML adalah sintaks array-of-tables. Jika Anda ingin array dari objek — misalnya, beberapa koneksi database — notasi seperti ini:

bagian adalah satu item dalam

[[databases]]
name = "primary"
host = "db1.example.com"

[[databases]]
name = "replica"
host = "db2.example.com"

mendapatkan bagian yang sama dari ruang yang tersisa setelah jarak dikurangi. Tiga kolom dengan [[double bracket]] array. Ini bekerja. Ini tidak ambigu. Tapi setiap pengembang yang membuka file TOML pertama kali bertanya, "apakah ini INI?" — karena tampilannya agak mirip. Ketidakfamiliaran ini memiliki biaya nyata ketika Anda menangani kontributor yang belum pernah melihat TOML sebelumnya. databases TOML juga tidak memiliki

tipe — secara sengaja. Jika skema Anda menggunakan null untuk berarti "kunci ada tetapi secara eksplisit tidak diatur", Anda akan perlu memodelkan hal ini secara berbeda (hapus kunci secara keseluruhan, atau gunakan nilai sentinel). Dan konfigurasi yang sangat terdalam menjadi panjang cepat: TOML tidak memiliki sistem anchor/alias YAML untuk mengulang bagian-bagian kecil, sehingga terjadi banyak salinan jika konfigurasi Anda memiliki struktur yang berulang. null Pengaturan TOML

Itu sangat berguna saat Anda mencoba membersihkan file TOML yang tumbuh secara organik seiring waktu. JSON: Musuh yang Anda Kenal

JSON dirancang untuk pertukaran data — mesin berkomunikasi dengan mesin — bukan untuk manusia menulis file konfigurasi. Akhirnya menjadi format konfigurasi karena setiap bahasa sudah memiliki parser JSON, dan kepraktisan itu menang. Sekarang kita memiliki package.json, tsconfig.json, .eslintrc.json, dan sekitar 40 konfigurasi JSON lainnya di setiap proyek JavaScript, yang semua diubah secara manual.

Tidak ada komentar. Masih.

Douglas Crockford menghapus komentar dari JSON secara sengaja pada tahun 2012 — ia khawatir pengembang akan menggunakan komentar sebagai instruksi parsing (serupa dengan komentar kondisional IE). Internet telah mengeluh tentang hal ini setiap hari sejak itu. Solusi yang digunakan orang:

JSONC

• — JSON dengan komentar. VS Code menggunakan ini untuk . Tidak dapat diproses oleh parser JSON standar. Bukan standar. settings.json dan launch.jsonJSON5
• — menambahkan komentar, koma akhir, kunci tanpa kutipan, string multi baris. Memiliki spesifikasi dan parser terpisah. Babel menggunakan ini untuk konfigurasi. Masih bukan JSON standar. kunci
• A "_comment" — field string yang menyimpan teks komentar Anda. Bekerja. Tampak buruk. Masuk ke dalam model data Anda. Juga tidak sah. Tambahkan koma akhir setelah item terakhir dalam array atau objek dan

Koma Trailing

menyebabkan JSON.parse — memberi tahu Anda ada masalah, tetapi tidak menunjukkan di mana koma yang salah tersebut. Ini adalah kesalahan parsing JSON nomor satu dalam file konfigurasi yang ditulis oleh manusia, dan terjadi karena setiap bahasa modern lainnya (array JavaScript, daftar Python, enum Rust) memungkinkan koma akhir, dan manusia menulis JSON secara manual dengan kebiasaan yang sama. SyntaxError: Unexpected token } Apa yang Diperoleh JSON

Sistem tipe tidak ambigu dan universal. Setiap parser JSON di setiap bahasa sepakat tentang apa yang

berarti. JSON Schema adalah pilihan validasi konfigurasi yang paling matang dari ketiga format ini — VS Code menggunakan ini untuk memvalidasi tsconfig.json dan package.json secara langsung, dengan penekanan kesalahan. Saat alat menulis konfigurasi Anda (webpack, tsc, npm), Anda tidak perlu peduli tentang kejelasan — itu yang dilakukan oleh true, 1, "1"dan null . Pemformat JSON Kesimpulan: Pilih Berdasarkan Konteks, Bukan Preferensi

Gunakan JSON

ketika alat menghasilkan atau mengonsumsi format ini (package.json, tsconfig, konfigurasi AWS, respons API GitHub), atau ketika Anda membutuhkan validasi JSON Schema. Jangan berjuang dengan menulisnya secara manual lebih dari diperlukan. Kehilangan komentar memang menyakitkan, tetapi keberadaan dan dukungan alat sangat sulit diperdebatkan. Gunakan YAML

ketika konfigurasi secara utama ditulis oleh manusia dan relatif datar — workflow GitHub Actions, file Docker Compose, manifest Kubernetes. Kutip semua yang bisa salah ditafsirkan sebagai boolean atau angka (string versi, kode negara, apa pun yang dimulai dengan angka). Jalankan lint. Jangan gunakan tab. Pertimbangkan inferensi tipe sebagai bug, bukan fitur. Gunakan TOML

ketika Anda mengontrol pilihan format dan ingin tidak ada koersi tipe yang mengejutkan. Ini adalah format yang paling jujur dari ketiga format tersebut tentang apa yang ia miliki. Jika Anda memulai proyek baru dan tidak ada alat yang memaksa Anda memilih format, TOML paling tidak mengejutkan Anda enam bulan ke depan. Ketidakfamiliaran ini adalah biaya sekali; kejelasan ini adalah permanen. ketika Anda mengontrol pilihan format dan tidak ingin ada koersi tipe yang mengejutkan. Ini yang paling jujur di antara tiga pilihan mengenai apa yang sebenarnya dimaksud. Jika Anda memulai proyek greenfield dan tidak ada alat yang memaksa penggunaan format tertentu, TOML paling tidak mengejutkan Anda dalam enam bulan ke depan. Ketidakfamiliaran ini adalah biaya sekali sekali; ketegasan ini adalah sesuatu yang permanen.

Anda mungkin juga menyukai