Konverter JSON ke YAML

Apa yang dilakukan alat ini

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

Konversi berjalan satu arah. Membaca YAML adalah masalah yang jauh lebih besar daripada menulisnya, dan 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 adalah persoalan yang terbatas, jadi itulah arah yang dicakup di sini.

Mengapa konverter sampai perlu punya pendapat

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

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

Masalah Norwegia, dan kerabatnya

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

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

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

Tak satu pun dari ini adalah bug dalam YAML. Mereka adalah penyelesai yang melakukan persis apa yang mereka janjikan, pada teks yang kebetulan cocok. Satu-satunya pertahanan adalah mengutip apa pun yang cocok, yaitu 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.

Persoalannya 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 pengaturan 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 merusak sintaksis ketimbang tipe

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.

• Titik dua diikuti spasi mengakhiri kunci. "note: time: now" akan dibaca sebagai kunci "note" yang nilainya kunci "time".
• Spasi diikuti tanda pagar memulai komentar, jadi segalanya setelahnya lenyap.
• Sebuah -, ?, :, [, ], {, }, #, &, *, !, |, >, %, @, atau backtick di depan adalah karakter indikator dan berarti sesuatu yang struktural.
• Spasi di awal atau ujung tak dipertahankan oleh nilai tanpa kutip, jadi " x " kembali sebagai "x".
• 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 — apostrof ditulis dua kali — dan lebih mudah dibaca daripada escape garis miring terbalik yang dibawa kutip ganda. Kutip ganda dicadangkan untuk kasus yang benar-benar butuh escape: karakter kontrol, tab, dan string multi-baris yang tak bisa memakai blok.

String multi-baris dan indikator kunyah

String yang mengandung baris-baru — skrip, sertifikat, 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 pipa, tempat teks muncul terindentasi dan terbaca di bawahnya.

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

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

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 string yang diakhiri dua baris-baru atau tak satu pun.

Skalar blok tak bisa membawa segalanya, dan di tempat ia tak bisa, keluaran kembali ke kutip ganda dan panel temuan mengatakan mengapa. Carriage return tak bertahan, karena skalar blok menormalkan pemutus baris. Baris pertama yang diawali spasi akan dibaca sebagai indentasi ekstra dan dilucuti. Dan baris yang diakhiri 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 keputusan ketimbang batasan, dan ia dilaporkan sebagai keputusan.

Lebih dari satu dokumen

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

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

Fallback hanya berlaku ketika seluruh masukan gagal terurai dan setiap baris berhasil, yang tak akan dilakukan dokumen yang sekadar cacat. Galat sintaksis tetap muncul sebagai 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 layak diketahui yang mana.

Kunci duplikat. JSON mengizinkan 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. Angka JSON yang lebih besar dari sekitar sembilan kuadriliun tak bertahan diurai menjadi double, jadi 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 pengenal besar penting, tempatnya adalah di dalam 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 diperlakukan format ini secara ketat. Dua spasi adalah konvensi; empat ditawarkan karena sebagian panduan gaya internal 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 dilipat dengan benar oleh kebanyakan penyunting.

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

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

Manifes Kubernetes dan bidang yang harus tetap string

Kubernetes membaca manifes dalam salah satu dari dua format itu. Dokumentasinya sendiri menyebut YAML sebagai kebiasaan dan menyebut JSON sebagai pilihan lain, dan kubectl mengubah manifes menjadi JSON, atau menjadi serialisasi lain yang didukung API, saat mengirim permintaan — jadi mengonversi bukan soal apa yang akan diterima klaster. Itu soal berkas yang tinggal pada Anda: YAML adalah yang dibaca peninjau, tempat perbedaan dalam pull request terbaca, dan satu-satunya dari keduanya yang bisa membawa komentar. JSON biasanya datang dari kubectl get -o json, dari templat, atau dari API yang mengembalikan objek.

• Satu berkas, beberapa objek. Manifes boleh dikumpulkan dalam satu berkas yang dipisah tiga tanda hubung, dan dokumentasi menyatakan dengan tegas bahwa objek dibuat dalam urutan kemunculannya — itulah sebabnya Service biasanya ditulis di atas Deployment yang mengisinya. Sakelar yang mengeluarkan tiap elemen larik tingkat-atas sebagai dokumen sendiri adalah yang mengubah daftar objek JSON menjadi berkas seperti itu.
• Entri lingkungan sebuah kontainer adalah dua bidang string. Rujukan API menyatakan name maupun value sebagai string, jadi nilai JSON berupa "true" harus keluar dengan kutipnya: tanpa kutip itu nilai boolean, dan boolean bukan tipe yang bidang itu dinyatakan menampung.
• Port kontainer dinyatakan sebagai bilangan bulat, dan ia duduk beberapa baris dari string-string itu. Keduanya menuntut perlakuan berlawanan, dan JSON sudah membawa pembedaannya: bilangan menjadi bilangan biasa, dan string dikutip hanya di tempat YAML akan berhenti membacanya sebagai string.
• Label dan anotasi adalah pemetaan dari string ke string. Di situlah masalah Norwegia mendarat di dalam manifes: label yang nilainya NO, on, atau off adalah boolean bagi pengurai YAML 1.1, dan nilai 1.10 adalah float yang kehilangan nol di ujungnya.

Tiga entri lingkungan, diberikan sebagai JSON dengan tiap nilainya string, terkonversi menjadi ini:

env:
  - name: DEBUG
    value: 'true'
  - name: REPLICAS
    value: '3'
  - name: COUNTRY
    value: 'NO'

Ketiganya dikutip, dan panel temuan menyebut ketiganya beserta nilai yang akan menjadi hasilnya: true adalah boolean, 3 adalah bilangan, dan NO adalah boolean false. Hanya yang terakhir bergantung pada versi — alihkan skema ke 1.2 dan kutipnya lepas, karena 1.2 tidak membaca NO sebagai apa pun selain teks. Dua yang lain menahan kutipnya di kedua versi.

Docker Compose, tempat rujukan format itu sendiri memperingatkan soal YAML

Berkas Compose adalah YAML, dan rujukan Docker untuknya memuat dua peringatan tentang penguraian YAML. Dokumentasi sebuah produk yang menyebut format serialisasinya sendiri sebagai bahaya adalah hal tak lazim, dan kedua peringatan itu tepat mengenai alasan keberadaan perkakas ini: nilai yang dimaksudkan sebagai teks tetapi dibaca pengurai sebagai hal lain.

• Port. Rujukan itu mengatakan pemetaan HOST:CONTAINER selalu harus diberikan sebagai string yang dikutip, untuk menghindari benturan dengan float basis 60 milik YAML. Tanpa kutip, 22:22 adalah bilangan bulat 1342.
• Nilai lingkungan. Rujukan itu meminta true, false, yes, dan no dilingkupi kutip agar pengurai tidak mengubahnya. Dua dari empat itu boolean di kedua versi YAML dan dua — yes dan no — hanya di 1.1, dan itulah sebabnya panel temuan menandainya berbeda.
• Aturan basis 60 hanya menjangkau pemetaan yang bilangan setelah titik duanya kurang dari enam puluh, karena itulah jangkauan satu digit basis 60. Maka 22:22 dikutip di sini dan 8080:80 dibiarkan biasa, dan bedanya adalah aturannya, bukan penilaian tentang port mana yang penting.

Layanan yang port dan nilai lingkungannya semua string di dalam JSON terkonversi menjadi ini:

services:
  proxy:
    image: nginx
    ports:
      - '22:22'
      - 8080:80
    environment:
      TLS_ENABLED: 'no'
      DEBUG: 'true'

Itulah keluaran yang diminta rujukan itu, dan skema bawaanlah yang menghasilkannya. Itu juga alasan paling jelas untuk tidak menyentuh skema: alihkan ke 1.2 dan pemetaan port serta no kehilangan kutipnya, sementara true tetap dengan kutipnya, karena 1.2 meninggalkan basis 60 dan menahan hanya true dan false sebagai boolean. Pengurai yang menerapkan 1.2 tetap membaca hasilnya dengan benar — tetapi nasihat Docker ditulis tanpa syarat semacam itu, dan menurutinya berharga dua pasang kutip.