Apa yang sebenarnya diselesaikan JSON Schema
Intinya: Schema mengatur struktur dan tipe, bukan makna bisnis. Ia menghentikan field yang hilang, tipe yang salah dan enum di luar rentang, sementara aturan seperti jumlah di atas nol tetap berada di kode.
Intinya: biarkan JSON Schema menegakkan struktur, tipe, rentang dan format, sementara aturan lintas-field, invarian bisnis dan state eksternal tetap di kode; adopsi untuk API publik dan payload bersama, bukan untuk service internal dengan lima field.
Ia menjawab "apakah bentuk data ini benar", bukan "apakah data ini masuk akal".
Yang ia lakukan dengan baik
Kelengkapan struktural. Field mana yang harus ada, apakah field tambahan diizinkan (required, additionalProperties).
Tipe. port sebagai angka atau string, tags sebagai array atau skalar. Ini saja menghapus banyak kode defensif di sistem multi-bahasa.
Rentang. enum, minimum/maximum, panjang string dan array.
Format. format untuk tanggal, email, URI dan UUID, dengan validator yang menegakkannya.
Pembenahan bersarang. Setiap level objek dan array mendapat batasannya sendiri, dan error membawa path yang presisi.
Dokumentasi. Schema adalah kontrak. Ubah satu field dan diff menunjukkan dampak rambatannya. Ia juga menghasilkan tipe dan form, sehingga satu definisi memberi makan beberapa konsumen.
Yang tidak bisa ia lakukan
Dependensi lintas-field. "Akhir harus setelah awal" bisa diungkapkan dengan if/then/else, tetapi hasilnya lebih panjang dan lebih sulit dibaca daripada tiga baris kode.
Invarian bisnis. "Stok tidak boleh negatif" bergantung pada state eksternal. Schema hanya melihat satu dokumen.
Semantik. price: -100 memenuhi {"type": "number"} dengan sempurna. Apakah itu harga yang sah berada di luar pengetahuan Schema.
Pembagian yang bisa dikerjakan
| Lapisan | Pemilik |
|---|---|
| Sintaks: apakah JSON-nya valid | Parser |
| Struktur: field, tipe, rentang, format | JSON Schema |
| Semantik: lintas-field, aturan bisnis, state eksternal | Kode aplikasi |
| Keamanan: ukuran, kedalaman, laju | Gateway / middleware |
Satukan semuanya di satu tempat dan Schema tumbuh menjadi ratusan baris dengan lima tingkat if/then. Pada titik itu orang akan mencari jalan memutarnya.
Kapan ini menguntungkan
- API publik dengan konsumen tak dikenal
- Beberapa service membaca payload yang sama
- Sistem berbasis konfigurasi yang salah ketik harus gagal cepat
- Menghasilkan tipe atau form dari kontrak
Untuk service internal kecil dengan lima field dan satu frontend, pemeriksaan yang ditulis tangan lebih cepat dipelihara. Memperkenalkan Schema di sana adalah kerja yang merugikan.
FAQ
Bagaimana saya memutuskan apakah akan mengadopsi JSON Schema?
Timbang konsumen publik, beberapa service yang membaca payload yang sama, dan kebutuhan menghasilkan tipe atau form. Untuk service internal kecil dengan lima field dan satu frontend, pemeriksaan yang ditulis tangan lebih cepat dipelihara.
Mengapa aturan lintas-field sebaiknya tetap di kode?
"Akhir harus setelah awal" bisa dipaksakan ke if/then/else, tetapi hasilnya lebih panjang dan lebih sulit dibaca daripada beberapa baris kode. Schema juga tidak bisa melihat state eksternal.
Haruskah Schema memvalidasi ukuran payload dan kedalaman bersarang?
Tidak. Schema mendeskripsikan struktur, bukan ukuran atau kedalaman; batas itu berada di lapisan gateway atau middleware.