Pengesahan JSON Schema: Panduan Lengkap untuk Mentakrifkan dan Mengesahkan Data JSON
Ketahui bagaimana JSON Schema berfungsi sebagai kontrak untuk data anda -- daripada jenis asas dan medan wajib hingga pengesahan format, versi draf dan kes penggunaan dunia sebenar untuk API dan fail konfigurasi.
Apa itu JSON Schema?
JSON Schema ialah bahasa deklaratif yang membolehkan anda menggambarkan struktur, kandungan dan kekangan dokumen JSON. Fikirkan ia sebagai kontrak antara pengeluar dan pengguna data. Pengeluar berkata "saya akan sentiasa menghantar objek dengan string name dan integer age", dan pengguna boleh mengesahkan bahawa setiap payload masuk benar-benar mematuhi janji tersebut sebelum memprosesnya.
Ini penting kerana JSON sendiri tidak mempunyai skema. Mana-mana nilai JSON yang sah adalah sah sepenuhnya. Kebebasan ini hebat untuk prototaip pantas, tetapi menjadi masalah apabila dua sistem perlu bersetuju tentang rupa data.
Mengapa JSON Schema Penting untuk API
API REST berkomunikasi melalui payload JSON, dan setiap endpoint mempunyai bentuk tersirat. JSON Schema menjadikan bentuk itu eksplisit dan boleh dibaca mesin. Dengan skema, anda boleh:
- Mengesahkan permintaan di pelayan sebelum ia mencapai logik perniagaan anda.
- Mengesahkan respons dalam ujian integrasi untuk menangkap perubahan yang merosakkan.
- Menjana dokumentasi secara automatik -- alat seperti Swagger/OpenAPI menggunakan JSON Schema sebagai tulang belakang.
- Menjana kod -- alat skema-ke-TypeScript, skema-ke-Go-struct menghapuskan definisi jenis manual.
Asas JSON Schema
Setiap JSON Schema sendiri adalah objek JSON. Skema paling mudah ialah objek kosong {}, yang menerima mana-mana JSON yang sah.
Jenis Primitif
Kata kunci type adalah asas. JSON Schema mengenal pasti enam jenis primitif:
| Jenis | Contoh JSON | Nota |
|---|---|---|
| string | "hello" | Nilai teks. Boleh dikekang dengan minLength, maxLength, pattern. |
| number | 3.14 | Mana-mana nilai berangka. Guna minimum, maximum, multipleOf. |
| integer | 42 | Nombor bulat sahaja. Kekangan sama seperti number. |
| boolean | true | Hanya true atau false. |
| object | {"kunci": "nilai"} | Pasangan kunci-nilai. Ditakrifkan dengan properties, required, additionalProperties. |
| array | [1, 2, 3] | Senarai teratur. Guna items, minItems, maxItems, uniqueItems. |
| null | null | Ketiadaan nilai. Sering digabung dengan jenis lain. |
Sifat dan Medan Wajib
Kata kunci properties mentakrifkan kunci yang dijangka. Kata kunci required menyenaraikan yang mana mesti ada.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name", "email"]
}Mengawal Sifat Tambahan
"additionalProperties": false menjadikan skema ketat -- hanya kunci yang disenaraikan dibenarkan.
additionalProperties: false bersama kata kunci komposisi seperti allOf, sifat yang ditakrifkan dalam sub-skema lain mungkin ditolak.
Pengesahan Format
Kata kunci format menyediakan pengesahan semantik melebihi jenis asas.
Format Terbina Dalam
| Format | Contoh Nilai | Kes Penggunaan |
|---|---|---|
| date-time | 2026-03-27T10:30:00Z | Cap masa ISO 8601 untuk peristiwa dan log |
| date | 2026-03-27 | Tarikh kalendar tanpa masa |
[email protected] | Borang hubungan, pendaftaran pengguna | |
| uri | https://example.com/api | URL webhook, pautan sumber |
| uuid | 550e8400-e29b-41d4-a716-446655440000 | Pengecam unik, kunci utama |
| ipv4 | 192.168.1.1 | Konfigurasi rangkaian, alamat pelayan |
Format sebagai Anotasi vs. Penegasan
Secara lalai, format adalah anotasi, bukan penegasan. Dalam Draft 2020-12, anda perlu mengaktifkan penegasan format secara eksplisit.
format dengan regex pattern jika pengesahan ketat adalah kritikal.
Versi Draf: Draft-07 vs 2020-12
Dua versi yang paling kerap anda temui ialah Draft-07 dan Draft 2020-12.
Perbezaan Utama
| Ciri | Draft-07 | Draft 2020-12 |
|---|---|---|
| prefixItems | Tidak tersedia | Menggantikan pengesahan tuple |
| $dynamicRef | Tidak tersedia | Baharu -- rujukan skema dinamik |
| unevaluatedProperties | Tidak tersedia | Menyelesaikan masalah additionalProperties + allOf |
| Sokongan perpustakaan | Cemerlang | Baik dan berkembang |
Versi Mana yang Perlu Dipilih?
Pilih Draft-07 jika ekosistem anda sudah menggunakannya atau anda memerlukan keserasian maksimum.
Pilih Draft 2020-12 jika anda memulakan projek baharu tanpa kekangan warisan.
Kesimpulan
Untuk kebanyakan projek baharu pada tahun 2026, Draft 2020-12 adalah pilihan lalai yang lebih baik.
Cara Menggunakan Penjana JSON Schema Kami
Penjana JSON Schema percuma kami mengambil mana-mana payload JSON dan menghasilkan skema yang sah secara automatik. Semuanya berjalan dalam pelayar anda.
Panduan Langkah demi Langkah
- Buka alat Penjana JSON Schema.
- Tampal JSON anda ke dalam kawasan input.
- Klik Jana dan alat akan menganalisis setiap medan, membuat inferens jenis dan mengesan format.
- Semak output -- skema yang dijana muncul di panel output.
- Tukar ke tab Sahkan untuk menguji skema anda terhadap payload JSON baharu.
- Salin skema dengan satu klik dan integrasikan ke dalam projek anda.
Nota Privasi
Penjana JSON Schema kami berjalan 100% dalam pelayar anda. Data JSON, skema yang dijana dan keputusan pengesahan anda tidak pernah meninggalkan peranti anda.
Jana JSON Schema Anda dengan Segera
Tampal mana-mana payload JSON dan dapatkan skema sedia guna dengan inferens jenis, medan wajib dan pengesanan format -- 100% dalam pelayar anda.