Konverter JSON ke YAML

Apa yang dilakukan alat ini

Ia mengonversi sebuah dokumen JSON menjadi YAML, lalu memberi tahu Anda mengapa setiap string berakhir dalam kutip. Bagian kedua itu adalah alasan alat ini ada: setiap konverter lain menyerahkan kembali keluaran dan membiarkan Anda menemukan kemudian bahwa salah satu nilai Anda bukan lagi sebuah string.

Konversi berjalan satu arah. Membaca YAML adalah masalah yang jauh lebih besar daripada menulisnya, dan sebuah pengurai YAML yang setengah-benar lebih buruk daripada tak ada sama sekali — ia menerima berkas Anda dan menyerahkan kembali data yang salah tanpa mengeluh. Memancarkan itu terbatas, jadi itulah arah yang dicakup di sini.

Mengapa sebuah konverter butuh pendapat sama sekali

JSON mengatakan tipe segala sesuatu. Sebuah string punya kutip, sebuah angka tidak, dan tak ada kemungkinan ketiga. YAML sebaliknya memutuskan tipe sebuah nilai tanpa kutip dengan melihat bentuknya: jika ia cocok pola untuk sebuah boolean ia sebuah boolean, jika ia cocok sebuah angka ia sebuah angka, dan hanya jika ia tak cocok apa pun ia dibiarkan sebagai teks.

Itulah yang membuat YAML menyenangkan untuk ditulis dengan tangan dan yang membuat mengonversi ke dalamnya sebuah panggilan penilaian. Setiap string dalam masukan harus diperiksa terhadap setiap pola yang diselesaikan YAML, dan dikutip jika ia cocok satu. Salah di arah aman dan keluarannya berisik; salah di arah lain dan sebuah nilai diam-diam berubah tipe.

Masalah Norwegia, dan kerabatnya

Kasus paling terkenal adalah sebuah daftar kode negara. Norwegia adalah NO, dan dalam YAML 1.1 token tanpa kutip NO adalah boolean false. Sebuah berkas konfigurasi yang mendaftar negara kehilangan Norwegia dan mendapat sebuah false, dan tak ada di mana pun melaporkan sebuah galat.

Ia bukan satu aturan aneh melainkan sebuah keluarga darinya. YAML 1.1 membaca semua y, Y, yes, no, on, dan off sebagai boolean, dalam setiap kapitalisasi, yang menjaring sebuah simbol kimia, sebuah posisi sakelar, dan sebuah jawaban atas sebuah pertanyaan. Dan penyelesai numeriknya lebih aneh lagi:

• 12:30 adalah 750. YAML 1.1 membaca digit yang dipisah titik-dua sebagai basis 60, jadi sebuah waktu hari atau sebuah durasi menjadi sebuah bilangan bulat.
• 0755 adalah 493. Sebuah nol di depan berarti oktal dalam YAML 1.1 — dan dalam YAML 1.2 teks yang sama adalah desimal 755, jadi kedua versi tak sepakat tentang angka mana ketimbang tentang apakah.
• 1.10 adalah 1.1. Sebuah nomor versi dua-bagian adalah sebuah float, dan nol di ujung lenyap. Sebuah dependensi yang dipaku ke 1.10 kini menunjuk ke 1.1.
• 2024-01-30 adalah sebuah objek tanggal, bukan sebuah string, karena YAML 1.1 punya sebuah tipe stempel waktu.
• Sebuah string kosong adalah null, begitu pula kata telanjang null, Null, NULL, dan tilde.

Tak satu pun dari ini adalah sebuah bug dalam YAML. Mereka adalah penyelesai melakukan persis yang mereka janjikan, pada teks yang kebetulan cocok. Satu-satunya pertahanan adalah mengutip apa pun yang cocok, yang adalah yang dilakukan alat ini dan yang diperhitungkan panel temuan baris demi baris.

Dua versi, dan mengapa yang lebih lama adalah default

YAML 1.2 tiba pada 2009 dan membuang sebagian besar penyelesai yang mengejutkan. Skema intinya menyimpan hanya true dan false sebagai boolean, membuang basis 60 sepenuhnya, dan tak punya tipe stempel waktu. Di bawah 1.2, NO dan 12:30 dan 2024-01-30 semuanya hanya string.

Tangkapannya adalah apa yang sebenarnya membaca berkas Anda. PyYAML mengimplementasikan YAML 1.1, dan PyYAML adalah pengurai di balik sejumlah besar perkakas — Ansible, klien Kubernetes lama, tak terhitung skrip. yaml.v3 milik Go dan js-yaml saat ini mengikuti 1.2. Jadi dokumen yang sama bisa dibaca dua cara berbeda bergantung pada siapa yang membukanya, dan satu-satunya keluaran yang aman di mana-mana adalah yang dikutip untuk 1.1.

Itu default di sini. Mengalihkan setelan ke 1.2 tak menyembunyikan apa pun — ia memancarkan ulang dengan penyelesai yang lebih baru dan panel temuan menyusut, jadi Anda bisa melihat persis kutip mana yang ada untuk skema yang lebih lama. Yang tinggal adalah yang dibutuhkan setiap pengurai.

String yang mematahkan sintaksis ketimbang tipe

Sebuah kelompok string kedua harus dikutip karena alasan berbeda: bukan karena YAML akan membacanya sebagai tipe lain, tetapi karena mereka tak akan terurai sebagai teks sama sekali.

• Sebuah titik-dua diikuti sebuah spasi mengakhiri sebuah kunci. "note: time: now" akan dibaca sebagai sebuah kunci "note" yang nilainya sebuah kunci "time".
• Sebuah spasi diikuti sebuah tanda pagar memulai sebuah komentar, jadi segalanya setelahnya lenyap.
• Sebuah -, ?, :, [, ], {, }, #, &, *, !, |, >, %, @, atau backtick di depan adalah sebuah karakter indikator dan berarti sesuatu yang struktural.
• Spasi di awal atau ujung tak dipertahankan oleh sebuah nilai tanpa kutip, jadi " x " kembali sebagai "x".
• Sebuah tab di mana pun dalam nilai ditolak langsung — PyYAML menolak seluruh dokumen ketimbang salah-membacanya, jadi yang ini gagal dengan lantang.

Kutip tunggal dipakai di mana pun mereka mencukupi, karena mereka punya persis satu aturan escape — sebuah apostrof ditulis dua kali — dan lebih mudah dibaca daripada escape garis miring terbalik yang dibawa kutip ganda. Kutip ganda dipesan untuk kasus yang benar-benar butuh escape: karakter kontrol, tab, dan string multi-baris yang tak bisa memakai sebuah blok.

String multi-baris dan indikator kunyah

Sebuah string yang mengandung baris-baru — sebuah skrip, sebuah sertifikat, sebuah blok prosa — biasanya adalah mengapa seseorang menginginkan YAML sejak awal. JSON hanya bisa menulisnya dengan escape garis-miring-terbalik-n pada satu baris yang sangat panjang; YAML punya skalar blok literal, diperkenalkan oleh sebuah pipa, tempat teks muncul terindentasi dan terbaca di bawahnya.

Kehalusannya adalah apa yang terjadi pada baris-baru di ujung, yang dikendalikan oleh indikator kunyah:

• Sebuah pipa telanjang memangkas: berapa pun baris-baru di ujung yang dimiliki blok, nilainya mendapat persis satu.
• Sebuah pipa diikuti sebuah minus melucuti: nilainya tak mendapat satu pun.
• Sebuah pipa diikuti sebuah plus menyimpan: nilainya mendapat setiap satunya.

Alat ini memilih indikator dari string yang diberikan kepadanya, jadi nilainya bertahan berpulang-pergi persis. Ia layak diketahui karena default — pipa telanjang — adalah yang orang tulis dengan tangan, dan ia diam-diam menormalkan sebuah string yang diakhiri dua baris-baru atau tak satu pun.

Sebuah skalar blok tak bisa membawa segalanya, dan di tempat ia tak bisa, keluaran kembali ke kutip ganda dan panel temuan mengatakan mengapa. Sebuah carriage return tak bertahan, karena skalar blok menormalkan pemutus baris. Sebuah baris pertama yang diawali sebuah spasi akan dibaca sebagai indentasi ekstra dan dilucuti. Dan sebuah baris yang diakhiri sebuah spasi dipertahankan oleh spesifikasi tetapi tak terlihat di layar dan dibuang kebanyakan penyunting saat simpan, jadi mengutipnya adalah pilihan yang lebih aman — yang itu adalah sebuah keputusan ketimbang sebuah batasan, dan ia dilaporkan sebagai satu.

Lebih dari satu dokumen

YAML punya sesuatu yang JSON tidak: sebuah berkas bisa menampung sebuah aliran dokumen yang dipisah tiga tanda hubung. Itu adalah format sebuah manifes Kubernetes, dan itu sebabnya sebuah larik JSON begitu sering perlu menjadi sesuatu selain sebuah urutan YAML.

Sakelar di sini memancarkan tiap elemen sebuah larik tingkat-atas sebagai dokumennya sendiri. Dan ketika masukan bukan sebuah nilai JSON tunggal sama sekali tetapi setiap baris terurai sendiri, ia dibaca sebagai NDJSON — format yang dibatasi-baris yang di dalamnya log dan ekspor API tiba — dan tiap baris menjadi sebuah dokumen. Pembacaan itu adalah sebuah tebakan, jadi ia dilaporkan di atas keluaran ketimbang dibuat senyap.

Fallback hanya berlaku ketika seluruh masukan gagal terurai dan setiap baris berhasil, yang tak akan dilakukan sebuah dokumen yang sekadar cacat. Sebuah galat sintaksis tetap muncul sebagai sebuah galat sintaksis, dengan baris dan kolom tempat ia terjadi.

Apa yang tak bisa dipertahankan konversi

Dua hal hilang sebelum alat ini melihat data Anda, keduanya dalam penguraian JSON itu sendiri, dan ia layak diketahui yang mana.

Kunci duplikat. JSON mengizinkan sebuah objek mendaftar kunci yang sama dua kali dan kebanyakan pengurai menyimpan yang terakhir secara senyap. YAML melarang duplikat langsung, jadi keluarannya akan valid, tetapi nilai yang lebih awal sudah hilang — dan tak ada konverter yang bisa melaporkan apa yang tak pernah diterimanya.

Presisi bilangan bulat. Sebuah angka JSON yang lebih besar dari sekitar sembilan kuadriliun tak bertahan diurai menjadi sebuah double, jadi sebuah ID seperti 12345678901234567890 kembali dibulatkan. Ini bukan masalah YAML dan bukan masalah yang diperkenalkan alat ini; ia terjadi di setiap pengurai JSON dalam bahasa itu. Jika sebuah pengenal besar penting, ia milik sebuah string di kedua sisi.

Catatan tentang keluaran

Indentasi adalah spasi, selalu, karena YAML melarang tab untuk indentasi sepenuhnya — itu salah satu dari sedikit hal yang formatnya ketat tentangnya. Dua spasi adalah konvensi; empat ditawarkan karena beberapa gaya rumah menginginkannya.

Urutan diindentasi di bawah kuncinya. Baik itu maupun bentuk tak-terindentasi adalah YAML yang sah dan berarti hal yang sama; yang terindentasi adalah yang kebanyakan orang tulis dan yang kebanyakan penyunting lipat dengan benar.

Sebuah larik atau objek kosong ditulis dalam gaya alir sebagai sepasang kurung siku atau kurawal, karena gaya blok tak punya cara mengungkapkan kekosongan — tak ada yang bisa ditulis pada baris berikutnya.

Keluaran diakhiri sebuah baris-baru, dan itu penopang-beban ketimbang kerapian. Pengunyahan sebuah skalar blok diukur terhadap pemutus baris yang mengikutinya, jadi sebuah blok terpangkas di ujung sebuah berkas tanpa sebuah baris-baru akhir kehilangan baris-baru yang seharusnya disimpannya.