Generator JSON Schema

JSON Schema Untuk Apa

JSON Schema adalah cara deklaratif untuk menggambarkan seperti apa seharusnya sebuah dokumen JSON: properti apa yang dimilikinya, tipe apa yang dipegang properti itu, apa yang wajib vs opsional, dan nilai apa yang sah. Ia adalah padanan dunia-JSON dari XSD untuk XML atau definisi tabel basis data. Proyek resminya berada di json-schema.org.

Di mana Anda akan menemukannya di alam liar:

• Kontrak API. OpenAPI 3.1 (rilisan Februari 2021) menanamkan JSON Schema langsung: setiap badan permintaan dan badan respons di spesifikasi API modern dijelaskan dengan fragmen JSON Schema.
• Autocomplete dan validasi IDE. settings.json VS Code, package.json dan tsconfig.json proyek Anda, berkas workflow.yml GitHub Actions semua di-autocomplete dan di-lint terhadap JSON Schema yang dipublikasikan.
• Validasi sisi server. Express / Fastify / Spring / Flask / FastAPI / Echo semua berintegrasi dengan validator JSON Schema (AJV, jsonschema, fastjsonschema) untuk menolak badan permintaan yang cacat sebelum mereka mencapai logika bisnis.
• Pembuatan kode. Alat seperti quicktype, json-schema-to-typescript, dan datamodel-code-generator mengubah skema menjadi struct Go, tipe TypeScript, dataclass Python, POJO Java, dst., menyediakan tipe agnostik bahasa dari satu sumber.
• Dokumentasi. Skema sekaligus berfungsi sebagai dokumentasi yang dapat dibaca mesin untuk setiap data berbentuk JSON yang Anda publikasikan.

Draf yang Akan Anda Temui di Alam Liar

Spesifikasi JSON Schema diterbitkan sebagai serangkaian draf. Draf stabil saat ini adalah 2020-12 (per halaman spesifikasi resmi: "The current version is 2020-12"). Draf yang mungkin Anda jumpai:

• Draft 4, lama tetapi masih dipakai; OpenAPI 3.0 memakai subset diperluas dari JSON Schema Specification Wright Draft 00 (kadang secara informal disebut Draft 5), yang dekat tetapi tidak identik dengan Draft 4.
• Draft 6, Draft 7, Draft 7 (2018) telah menjadi draf produksi yang dominan bertahun-tahun dan masih sangat umum di perkakas warisan.
• Draft 2019-09, draf pertama yang memakai konvensi pengenal tahun-bulan; memperkenalkan $defs di samping kata kunci definitions warisan.
• Draft 2020-12, draf stabil saat ini dan yang dipancarkan generator ini. Selaras dengan OpenAPI 3.1.

Jika ragu, pilih draf yang cocok dengan validator Anda. AJV (validator JavaScript paling populer) mendukung Draft 04, 06, 07, 2019-09, dan 2020-12 dengan opt-in eksplisit. jsonschema di Python juga sama. Jika Anda tidak tahu apa yang diinginkan konsumen di hilir, 2020-12 adalah bawaan aman untuk pekerjaan baru.

Tipe Bawaan

JSON Schema menggambarkan tujuh tipe dasar yang sesuai dengan jenis nilai JSON:

Kata kunci komposisi memungkinkan Anda mencampur-mencocokkan: oneOf (tepat satu), anyOf (paling sedikit satu), allOf (semuanya), not (kebalikannya). Plus enum untuk daftar terbatas nilai yang diizinkan dan const untuk satu nilai tetap.

Apa yang Bisa dan Tidak Bisa Diberi Tahu Skema Auto-Generated kepada Anda

Menyimpulkan skema dari satu contoh JSON itu kuat tetapi terbatas. Generator dapat mendeteksi:

• Tipe setiap nilai daun (string vs angka vs boolean vs array vs objek).
• Struktur objek dan array bersarang.
• Kunci yang muncul di contoh (dan menandai sebagai required jika Anda memilihnya).

Tidak dapat mendeteksi:

• Kolom opsional. Kunci di contoh Anda mungkin opsional di spesifikasi aslinya, tetapi satu contoh tidak dapat memberitahu Anda yang mana. Semuanya tampak wajib secara bawaan.
• Petunjuk format. String "2024-04-12" tampak seperti tanggal, tetapi bisa juga label teks bebas yang kebetulan berbentuk tanggal. Tambah format: date dengan tangan jika kolom itu memang tanggal.
• Batasan validasi. Panjang maksimum, nilai enum yang diizinkan, pola regex: semua butuh masukan manusia.
• String dokumentasi. title, description, dan examples pada setiap kolom meningkatkan pengalaman pengembang tetapi butuh kurasi.
• Varian. Jika satu kolom bisa berupa string atau angka tergantung konteks, satu contoh akan memilih salah satu dan melewatkan yang lain. Gabungkan beberapa contoh atau gunakan oneOf secara manual.

Perlakukan keluaran sebagai titik awal yang 70% jadi. Tambahan bernilai (kolom mana yang benar-benar wajib, format string apa yang berlaku, kisaran nilai apa yang diizinkan, makna setiap kolom) adalah langkah kurasi manusia.

Dua Jebakan Halus yang Patut Diketahui

• format bersifat anjuran secara bawaan di 2020-12. Kosakata format-annotation menandai format: email sebagai petunjuk, bukan aturan validasi keras, kecuali validator Anda secara eksplisit memilih format-assertion. Jadi string yang tidak cocok dengan regex email tetap lulus secara bawaan. Mode strict AJV dan paket ajv-formats menambahkan validasi format penuh; periksa bawaan validator Anda sebelum mengandalkan pemeriksaan format untuk masukan yang kritis bagi keamanan.
• additionalProperties: false tidak bekerja sama baiknya dengan allOf. Jika Anda menyusun skema dengan allOf untuk validasi ala-pewarisan, additionalProperties: false pada satu cabang tidak melihat properti yang didefinisikan di cabang saudara, sehingga kolom yang sah gagal validasi. Perbaikannya di Draft 2019-09+ adalah unevaluatedProperties: false, yang sadar komposisi.

JSON Schema vs Zod / Joi / Yup vs Tipe TypeScript

Beberapa teknologi tumpang tindih dengan peran JSON Schema; masing-masing punya titik kuat sendiri:

• JSON Schema. JSON deklaratif, validasi saat runtime, agnostik bahasa. Menang ketika kontrak API melintasi batas bahasa (misalnya server Go, pipeline data Python, dan frontend TypeScript semua mengonsumsi API yang sama).
• Tipe TypeScript. Hanya saat kompilasi. Indah untuk keamanan tipe in-process di dalam kodebasis TS tetapi menghilang saat runtime, tidak memberikan validasi JSON yang masuk. Alat seperti json-schema-to-typescript menghasilkan tipe dari skema untuk dua keuntungan sekaligus.
• Zod, Joi, Yup. Validasi saat runtime code-first di JavaScript atau TypeScript, dengan inferensi TypeScript bawaan. Satu bahasa, tetapi pengalaman pengembang sangat baik di dalam bahasa itu. Skema adalah objek JS, bukan JSON portabel.
• Pydantic dan Marshmallow. Padanan Python: validasi saat runtime berbasis kelas dengan type hint Python.

Jika skema Anda perlu dikonsumsi oleh banyak bahasa atau alat (IDE, perkakas OpenAPI, generator kode), JSON Schema adalah rumah yang tepat. Jika Anda tetap di dalam satu bahasa, opsi native bahasa itu biasanya lebih enak ditulis.

Kasus Penggunaan Umum

• Membangun awal spesifikasi OpenAPI. Tempelkan respons API nyata, hasilkan skemanya, taruh di components.schemas.
• Menghasilkan tipe TypeScript / Go / Python lewat quicktype atau yang serupa, menyediakan tipe agnostik bahasa dari satu sumber.
• Memvalidasi masukan tak tepercaya di endpoint server dengan AJV / jsonschema / Pydantic.
• Menulis autocomplete IDE untuk format konfigurasi kustom. VS Code, IDE JetBrains, dan lainnya membaca JSON Schema untuk menggerakkan autocomplete file JSON.
• Mendokumentasikan bentuk berkas konfigurasi untuk konsumen di hilir.
• Migrasi antar format data. JSON Schema yang dihasilkan dari satu sumber dapat menggerakkan validasi, transformasi, atau dokumentasi di hilir.

Kesalahan Umum

1. Memperlakukan skema auto-generated sebagai spesifikasi final. Itu hanyalah titik awal. Tambahkan petunjuk format, tandai kolom yang benar-benar opsional, tambahkan dokumentasi, set kisaran nilai.
2. Melewatkan deklarasi $schema. Validator memakainya untuk tahu draf mana yang diterapkan. Selalu sertakan di bagian atas skema.
3. Memperlakukan required sebagai atribut per-properti. Tidak seperti XSD atau skema Mongoose, required di JSON Schema adalah sebuah array di tingkat objek induk yang mencantumkan nama properti yang wajib.
4. Lupa additionalProperties: false ketika Anda ingin validasi ketat. Bawaannya true, artinya kunci tak dikenal diam-diam diizinkan.
5. Mengacaukan enum dengan examples. enum = daftar nilai yang diizinkan (validasi). examples = nilai contoh hanya untuk dokumentasi (tanpa efek validasi).
6. Mengasumsikan format ditegakkan. Secara bawaan di Draft 2020-12 ia adalah anotasi, bukan asersi; regex email Anda tidak akan jalan kecuali Anda memilih untuk mengaktifkannya.
7. Menyimpulkan opsionalitas dari satu contoh. Setiap kunci di contoh Anda menjadi wajib secara bawaan. Spesifikasi nyata hampir selalu punya kolom opsional; hapus mereka dari array required sebagai bagian dari kurasi.

Lebih Banyak Pertanyaan yang Sering Diajukan

Apakah skema akan bekerja dengan OpenAPI 3.1?

Ya. OpenAPI 3.1 (dirilis Februari 2021) menyelaraskan bahasa skemanya sepenuhnya dengan JSON Schema Draft 2020-12, yang dipancarkan generator ini. Letakkan skema di components.schemas di dokumen OpenAPI Anda dan rujuk lewat $ref. OpenAPI 3.0 lebih lama memakai subset sebelumnya; Anda mungkin perlu menyesuaikan jika menargetkan 3.0.

Bisakah saya menghasilkan tipe di bahasa saya dari skema ini?

Ya. quicktype menghasilkan TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm, dan lainnya dari sebuah JSON Schema. json-schema-to-typescript adalah alternatif khusus JS. Sebagian besar bahasa modern memiliki setidaknya satu alat skema-ke-tipe; skema yang dihasilkan berfungsi sebagai masukan untuk mereka semua.

Apa beda antara $defs dan definitions?

Keduanya adalah tempat untuk meletakkan sub-skema yang dapat dipakai ulang dan dapat Anda $ref di tempat lain di dokumen. definitions adalah nama warisan, dipakai di Draft 04, 06, dan 07. $defs adalah nama saat ini, diperkenalkan di Draft 2019-09 dan berlanjut di 2020-12. Setara secara fungsi, tetapi gunakan $defs untuk pekerjaan baru.

Apakah JSON saya dikirim ke mana pun?

Tidak. Pembuatan skema berjalan sepenuhnya di peramban Anda. JSON yang ditempel diurai secara lokal, ditelusuri, dan dipancarkan sebagai skema di textarea keluaran. Tidak ada yang diunggah ke server, dicatat, atau disimpan setelah Anda menutup tab. Ini penting karena contoh JSON sering berisi data nyata (rekaman pelanggan, respons API internal, info pegawai) yang tidak ingin Anda alirkan lewat pihak ketiga.

Kenapa skema array saya hanya menggambarkan elemen pertama?

Inferensi dari satu contoh memperlakukan array sebagai homogen: melihat elemen pertama dan mengasumsikan sisanya cocok. Jika array sebenarnya dapat menahan bentuk berbeda, Anda perlu menulis items sebagai { "oneOf": [...] } dengan tangan. Atau jalankan generator pada setiap varian secara terpisah dan gabungkan skemanya.

Apakah saya perlu memakai generator sama sekali, atau menulis skema dengan tangan?

Untuk skema kecil yang Anda kendalikan dari ujung ke ujung, menulis dengan tangan mengajarkan Anda spesifikasi lebih cepat. Untuk respons API besar dengan puluhan objek bersarang, generasi membawa Anda ke draf dalam hitungan detik dan Anda habiskan waktu yang dihemat untuk merawat batasan, deskripsi, dan array required. Sebagian besar pengembang yang bekerja melakukan keduanya: hasilkan, lalu rawat.