Apa yang sebenarnya diselesaikan oleh JSON Schema
Inti pati: Schema mengawal struktur dan jenis, bukan makna perniagaan. Ia menghalang medan hilang, jenis salah dan enum di luar julat, manakala peraturan seperti amaun melebihi sifar kekal dalam kod.
Pokoknya: biarkan JSON Schema menguatkuasakan struktur, jenis, julat dan format, manakala peraturan merentas medan, invarian perniagaan dan keadaan luaran kekal dalam kod; gunakannya untuk API awam dan muatan dikongsi, bukan untuk perkhidmatan dalaman lima medan.
Ia menjawab "adakah data ini berbentuk betul", bukan "adakah data ini masuk akal".
Apa yang ia lakukan dengan baik
Kelengkapan struktur. Medan mana yang mesti wujud, sama ada medan tambahan dibenarkan (required, additionalProperties).
Jenis. port sebagai nombor atau rentetan, tags sebagai tatasusunan atau skalar. Ini sahaja membuang banyak kod pertahanan dalam sistem berbilang bahasa.
Julat. enum, minimum/maximum, panjang rentetan dan tatasusunan.
Format. format untuk tarikh, emel, URI dan UUID, dengan pengesah yang menguatkuasakannya.
Penyarangan. Setiap tahap objek dan tatasusunan mendapat kekangannya sendiri, dan ralat membawa laluan yang tepat.
Dokumentasi. Schema ialah kontrak. Ubah satu medan dan diff menunjukkan kawasan kesannya. Ia juga menjana jenis dan borang, jadi satu definisi memberi makan kepada beberapa pengguna.
Apa yang ia tidak boleh lakukan
Kebergantungan merentas medan. "Tamat mesti selepas mula" boleh dinyatakan dengan if/then/else, tetapi hasilnya lebih panjang dan lebih sukar dibaca daripada tiga baris kod.
Invarian perniagaan. "Stok tidak boleh menjadi negatif" bergantung pada keadaan luaran. Schema hanya melihat satu dokumen.
Semantik. price: -100 memenuhi {"type": "number"} dengan sempurna. Sama ada ia harga yang sah berada di luar pengetahuan Schema.
Pembahagian yang boleh dilaksanakan
| Lapisan | Pemilik |
|---|---|
| Sintaks: adakah JSON sah | Penghurai |
| Struktur: medan, jenis, julat, format | JSON Schema |
| Semantik: merentas medan, peraturan perniagaan, keadaan luaran | Kod aplikasi |
| Keselamatan: saiz, kedalaman, kadar | Gateway / middleware |
Gabungkan semuanya di satu tempat dan Schema berkembang kepada ratusan baris dengan lima tahap if/then. Pada ketika itu orang akan mengelilinginya.
Bila ia berbaloi
- API awam dengan pengguna yang tidak diketahui
- Berbilang perkhidmatan membaca muatan yang sama
- Sistem dipacu konfigurasi yang kesilapan taipnya mesti gagal dengan segera
- Menjana jenis atau borang daripada kontrak
Untuk perkhidmatan dalaman kecil dengan lima medan dan satu frontend, semakan tulisan tangan lebih pantas untuk diselenggara. Memperkenalkan Schema di situ ialah kerja negatif.
Soalan Lazim
Bagaimana saya menentukan sama ada untuk mengguna pakai JSON Schema?
Timbangkan pengguna awam, berbilang perkhidmatan yang membaca muatan yang sama, dan keperluan untuk menjana jenis atau borang. Untuk perkhidmatan dalaman kecil dengan lima medan dan satu frontend, semakan tulisan tangan lebih pantas untuk diselenggara.
Mengapa peraturan merentas medan harus kekal dalam kod?
"Tamat mesti selepas mula" boleh dipaksa ke dalam if/then/else, tetapi hasilnya lebih panjang dan lebih sukar dibaca daripada beberapa baris kod. Schema juga tidak dapat melihat keadaan luaran.
Patutkah Schema mengesahkan saiz muatan dan kedalaman penyarangan?
Tidak. Schema menerangkan struktur, bukan saiz atau kedalaman; had tersebut tergolong dalam lapisan gateway atau middleware.