Nama anggota belum menjadi path
Pertimbangkan sebuah objek JSON yang kuncinya adalah draft/a~b dan nilainya adalah objek lain yang berisi state. Slash adalah bagian dari kunci; tidak membuat level bersarang. Sebuah JSON Pointer, sebaliknya, mengidentifikasi nilai melalui token referensi yang dipisahkan oleh slash. Penunjuk /orders/0/item dapat mengarahkan sebuah item di dalam sebuah array, di mana 0 adalah indeks array. Menyalin nama anggota mentah ke dalam sebuah pointer tanpa escape dapat karena itu mengarahkan ke tempat yang salah atau gagal sepenuhnya.
RFC 6901 mendefinisikan dua escape di dalam setiap token: tilde menjadi ~0 dan slash menjadi ~1. Seluruh pointer juga dimulai dengan slash untuk setiap segmen, sementara pointer kosong mengacu pada seluruh dokumen. Notasi ini berkaitan dengan karakter dalam sebuah path, bukan isi dari nilai yang diajukan. Hal ini tidak mengubah objek JSON sendiri. Gunakan alat token ketika Anda merakit sebuah jalur dari nama anggota yang disediakan oleh data atau pengguna.
Bangun contoh satu segmen per kalinya
Untuk kunci draft/a~b, pertama ganti tilde dengan ~0, kemudian slash dengan ~1. Token yang di-escape adalah draft~1a~0b. Prefiks slash dan tambahkan properti terpisah bernama state untuk mendapatkan /draft~1a~0b/state. Konverter tertanam di bawah ini melakukan langkah token; dengan sengaja tidak menambahkan slash awal karena Anda mungkin ingin meletakkan token di manapun pada penanda yang lebih panjang. Bandingkan keluarannya dengan tiga tahap di diagram.
Alat token invers menggantikan ~1 dengan slash sebelum menggantikan ~0 dengan tilde. Urutan itu penting: dekoding ~01 sebagai ~1, kemudian dekodingnya lagi sebagai slash akan mengubah nama asli. Sebuah token pointer bukanlah enkoding persentase URL. Jika sebuah aplikasi menempatkan sebuah pointer di dalam fragmen URL, lapisan URI luar memiliki aturan encoding tambahan. Jaga sintaks pointer dan sintaks URL terpisah saat mendebug sebuah tautan atau permintaan API.
- Kunci raw: draft/a~b
- Token yang di-escape: draft~1a~0b
- Jalur lengkap: /draft~1a~0b/state
Apa yang benar-benar dihasilkan oleh pengurangan
Alat flatten berjalan objek JSON dan menulis nilai daun di bawah kunci yang terlihat seperti lengkap JSON Pointers. Untuk objek yang berisi properti bernama state di bawah draft/a~b, satu entri datar adalah /draft~1a~0b/state dengan nilai daun yang sama. Ini dapat membuat data bersarang lebih mudah dibandingkan, daftar atau ekspor. Alat terbalik membaca kunci-kunci jalur tersebut untuk membangun kembali objek bersarang, dengan syarat jalur tidak bertabrakan atau saling bertentangan. Entri datar masih merupakan anggota objek JSON, bukan operasi pencarian otomatis.
Alat ini memperlakukan array sebagai nilai daun; tidak membuat entri /0 dan /1 terpisah untuk elemen mereka. Objek kosong juga daun. Sebuah pointer JSON umum dapat mengarahkan indeks array, tetapi daftar rata dari alat ini tidak mengelompokkan indeks tersebut. Jika satu jalur menempatkan nilai skalar pada /a sementara yang lain mencoba mengalokasikan /a/b, operasi terbalik harus menolak konflik. Pertahankan JSON asli ketika mengubah kunci jalur secara manual.
Aliran kerja yang aman untuk data berbasis path
Mulai dengan JSON yang valid dan putuskan apakah Anda membutuhkan alamat tunggal atau tampilan datar lengkap. Untuk satu alamat, bagi rute yang diinginkan menjadi nama anggota yang sebenarnya, escape setiap nama secara terpisah, dan bergabung dengan token dengan slashes awal. Jangan escape seluruh penanda dalam satu jalan: itu akan mengubah pemisah slashes menjadi bagian dari nama. Jika Anda perlu memeriksa banyak nilai daun, ratakan objek dan periksa kunci yang dihasilkan sebelum berbagi dengan sistem lain.
Ketika memulihkan data, periksa bahwa setiap kunci datar dimulai dengan slash dan bahwa ~ escapenya valid. Perhatikan untuk tugas yang duplikat atau berkonflik, array yang diperlakukan sebagai daun dan kunci literal yang kebetulan mengandung titik atau slashes. Uji perjalanan pulang-pergi dengan objek kecil yang berisi kedua karakter tanda baca, lalu bandingkan struktur JSON yang dianalisis daripada indentasi. Standar-standar ini menjelaskan sintaks pointer; kebijakan flattening yang tepat adalah fitur dari alat lokal ini dan harus diperiksa sebelum membangun aliran kerja di sekitarnya.