JSON Stringify

Apa yang sebenarnya dilakukan escaping

Stringify mengurai JSON Anda, meminifikasinya, lalu membungkus hasilnya dengan tanda kutip ganda dan meng-escape semua yang bisa membuat string berakhir terlalu cepat. Tanda kutip ganda di dalamnya menjadi \", backslash digandakan menjadi \\, dan karakter kontrol di bawah U+0020 menjadi bentuk singkatnya \n, \r, \t, \b, dan \f, atau escape \u00XX jika tidak ada bentuk singkatnya.

Ada dua hal yang sengaja dibiarkan. Garis miring tidak di-escape, karena JSON tidak mewajibkannya; kadang Anda melihat \/ di output alat lain, yang sah tetapi tidak perlu dan berasal dari kebiasaan lama menyembunyikan urutan </script> di dalam HTML. Karakter non-ASCII juga dibiarkan apa adanya alih-alih diubah menjadi escape \u, sehingga teks beraksen, aksara CJK, dan emoji tetap terbaca. Kedua bentuk bermakna sama bagi parser, dan bentuk yang terbaca lebih mudah dibandingkan.

Encoding ganda, dan mengapa merepotkan

Alat ini ada karena escaping tidak idempoten, dan orang biasanya menyadarinya di tengah men-debug hal lain. Escape sebuah dokumen sekali, dan tanda kutip menjadi \". Escape hasilnya lagi, dan menjadi \\\", karena backslash yang baru saja ditambahkan kini juga merupakan karakter yang perlu di-escape. Setiap putaran kira-kira menggandakan jumlah backslash.

Inilah ciri payload yang diserialisasi dua kali: field yang seharusnya berisi objek malah berisi string JSON, dan tanda kutipnya terlihat diberi backslash saat Anda membaca log. Ini terjadi ketika kode memanggil serializer pada nilai yang sudah diserialisasi oleh framework, dan perbaikannya hampir selalu menghapus salah satu dari dua panggilan itu, bukan menambahkan langkah decoding.

Unstringify adalah alat untuk mengurainya. Jalankan sekali untuk setiap lapisan encoding dan perhatikan backslash berkurang setengahnya setiap kali. Ketika backslash hilang dan hasilnya bisa diurai sebagai objek, Anda tahu ada berapa lapisan.

Kapan string yang di-escape Anda perlukan

Saat menyematkan payload di dalam dokumen JSON lain, cara yang umum dipakai amplop webhook, antrean job, dan log audit untuk membawa isi apa pun. Saat mengisi variabel lingkungan dengan nilai JSON, yang tanda kutipnya akan dimakan shell jika tidak di-escape. Saat menempelkan body request ke file YAML untuk job CI. Saat menulis fixture tes sebagai literal di kode sumber. Saat menyimpan dokumen di kolom teks, bukan kolom JSON bawaan.

Dalam setiap kasus, tanda kutip di dalamnya harus melewati satu lapisan parsing yang jika tidak akan menganggapnya sebagai penutup, dan escaping-lah yang membawanya lewat dengan utuh.

Aturan escape, satu karakter demi satu karakter

JSON menetapkan dengan tepat karakter mana saja yang tidak boleh muncul apa adanya di dalam sebuah string. Tanda kutip ganda akan menutup string terlalu cepat, jadi ia ditulis \". Backslash adalah awal dari sebuah escape, jadi ia digandakan menjadi \\. Semua karakter kontrol di bawah U+0020 dilarang, dan lima di antaranya punya bentuk singkat: baris baru adalah \n, carriage return \r, tab \t, backspace \b, dan form feed \f. Sisanya pada rentang itu ditulis sebagai escape enam karakter seperti \u0000.

Ada dua karakter yang sering di-escape padahal tidak diwajibkan. Garis miring boleh ditulis \/, yang sah tetapi tidak perlu; kebiasaan ini berasal dari menyisipkan JSON ke dalam HTML, karena di sana urutan </script> akan menutup elemen script lebih awal. Karakter non-ASCII juga boleh ditulis sebagai escape \u, dan sebagian pustaka melakukannya secara bawaan agar keluarannya tetap ASCII murni.

Alat ini membiarkan keduanya apa adanya, karena keluaran yang mudah dibaca lebih enak dibandingkan lewat diff dan semua parser memperlakukan kedua bentuk itu secara identik. Kalau sistem di hilir memang benar-benar membutuhkan keluaran ASCII saja, itu urusan opsi pada serializer, bukan sesuatu yang dituntut oleh dokumennya.

Mengirim JSON dengan aman lewat shell

Shell adalah tempat escape paling sering meleset, karena dua lapis tanda kutip berlaku sekaligus. Tanda kutip tunggal di bash meneruskan semuanya apa adanya, itulah sebabnya curl -d '{"name":"value"}' berhasil sementara string yang sama dengan kutip ganda tidak — shell lebih dulu mengembangkan variabel dan membuang sejumlah karakter sebelum curl sempat melihatnya.

Ketika payload-nya sendiri mengandung tanda kutip tunggal, bentuk berkutip tunggal pun ikut rusak, dan jawaban yang kokoh adalah berhenti menaruhnya di baris perintah: tulis body ke sebuah berkas lalu pakai curl -d @body.json, atau salurkan lewat pipe. Untuk payload yang dibangkitkan program, jq -n lebih aman daripada menyambung string karena hasilnya otomatis berupa JSON yang sah.

Variabel lingkungan yang menyimpan JSON adalah kasus sejenis, terutama pada konfigurasi CI dan Docker. Nilainya biasanya harus selamat melewati pengutipan YAML, ekspansi shell, dan parsing aplikasi itu sendiri — tiga lapis sekaligus — dan cara menjaga kewarasan adalah meng-encode JSON itu dengan base64, mengoper hasilnya, lalu men-decode-nya di titik pemakaian.

Log terstruktur dan jejak encoding ganda

Pipeline log makin sering mengharapkan satu objek JSON per baris, sehingga setiap field bisa dicari tanpa harus menembakkan regular expression ke teks bebas. Jebakannya adalah mencatat objek yang sudah terlanjur diserialisasi: field itu tiba sebagai string JSON, bukan objek bersarang, dan sistem log mengindeksnya sebagai satu gumpalan yang tidak tembus pandang.

Tanda yang kelihatan persis jejak yang ingin diurai oleh alat ini — nilai yang terbaca sebagai {\"id\":42} alih-alih {"id":42}. Setiap lapisan tambahan kira-kira melipatgandakan jumlah backslash, jadi menghitungnya sudah cukup untuk tahu berapa kali encoding terjadi.

Perbaikannya ada di sisi penghasil log. Oper objeknya ke logger dan biarkan ia melakukan serialisasi sekali saja, bukan Anda yang menyerialisasi lalu mengoper string. Kalau string itu datang dari tempat lain dan tidak bisa diubah, kebanyakan platform log punya filter parsing JSON yang bisa membuka field tersebut saat data masuk, dan itu lebih baik daripada melakukannya di setiap kueri.

Menyisipkan payload ke dalam dokumen lain

Amplop webhook, antrean pekerjaan, dan log audit menghadapi masalah yang sama: sebuah pembungkus dengan field-nya sendiri harus membawa isi yang bentuknya bebas. Menyerialisasi isi itu menjadi string adalah jawaban paling sederhana, dan harganya adalah dokumen di dalamnya menjadi tidak tembus pandang — ia tidak bisa dikueri, divalidasi, atau diindeks tanpa di-parse untuk kedua kalinya.

Pilihan lainnya, membiarkan isi itu tetap sebagai objek bersarang, menjaga agar ia tetap bisa dikueri, tetapi menuntut skema pembungkusnya mengizinkan struktur bebas dan mencampur dua ruang nama di mata apa pun yang menelusuri dokumen tersebut. Kebanyakan sistem akhirnya memilih per kebutuhan: bersarang bila isinya perlu diperiksa, dijadikan string bila ia hanya diteruskan.

Ada pilihan ketiga yang layak diingat ketika payload-nya besar atau berupa data biner: simpan di tempat lain dan kirim rujukannya saja. Sebuah URL beserta checksum di dalam amplop menghindarkan Anda dari urusan escape sekaligus batas ukuran, dan begitulah biasanya alur kerja berkas besar berakhir.

Membaca teks ber-escape tanpa alat bantu

Mengurai encoding dengan mata sendiri masih mungkin untuk nilai yang pendek dan layak dilatih, karena dari situ Anda tahu apa yang sebenarnya terjadi. Satu lapis memperlihatkan \" di sekitar key dan value. Dua lapis memperlihatkan \\\" dan string-nya biasanya dibungkus tanda kutip yang juga ikut di-escape. Lebih dalam dari itu, backslash-nya jadi lebih banyak daripada isinya dan menghitung lebih cepat daripada membaca.

Pemeriksaan yang berguna adalah bagian awal string. Objek yang bersarang dengan benar diawali kurung kurawal tanpa escape; yang ter-encode dua kali diawali tanda kutip lalu kurung kurawal ber-escape, dan bentuk itu akan langsung Anda kenali begitu terbiasa.

Di terminal, printf '%s\n' "$value" membuka satu lapis dan jq -r '.' membuka satu lapis lagi, jadi menerapkannya bergantian sambil melihat jumlah backslash berkurang separuh setiap kali adalah versi command line dari apa yang dilakukan tombol unstringify di sini.