Dasar-Dasar JSON Schema

JSON Schema mendefinisikan struktur dan aturan validasi untuk data JSON. Ini berfungsi seperti kontrak untuk format data Anda, memungkinkan Anda menentukan bidang apa yang diharapkan, tipe apa yang seharusnya, dan batasan apa yang harus dipenuhi. Dengan mendefinisikan JSON Schema, Anda dapat secara otomatis memvalidasi data yang masuk, menangkap kesalahan lebih awal, mendokumentasikan format yang diharapkan dari API Anda, dan menghasilkan data tiruan yang sesuai dengan spesifikasi Anda. JSON Schema tidak tergantung bahasa dan didukung oleh puluhan pustaka di hampir semua bahasa pemrograman, menjadikannya standar universal untuk validasi data JSON.

Mengapa Menggunakan JSON Schema?

Memvalidasi data JSON secara manual dengan pernyataan if dan pemeriksaan tipe dengan cepat menjadi tidak terawat seiring kompleksitas struktur data Anda. JSON Schema menyediakan pendekatan deklaratif yang memisahkan logika validasi dari kode bisnis Anda. Pemisahan ini menawarkan beberapa keuntungan. Anda dapat menggunakan kembali schema yang sama di validasi frontend dan backend, memastikan konsistensi di seluruh tumpukan aplikasi Anda. Anda dapat menghasilkan dokumentasi interaktif yang menunjukkan kepada pengguna format data apa yang diharapkan API Anda. Anda dapat mengotomatiskan pengujian dengan memvalidasi data tiruan terhadap schema Anda sebelum menerapkan perubahan. Anda dapat mendeteksi perubahan yang merusak ketika schema Anda berevolusi dengan membandingkan versi lama dan baru. Anda juga dapat menghasilkan formulir antarmuka pengguna secara otomatis dari schema, karena pustaka formulir populer mendukung rendering JSON Schema.

Memahami Struktur Schema Dasar

JSON Schema adalah dokumen JSON itu sendiri yang menggambarkan struktur dokumen JSON lainnya. Berikut adalah contoh mendasar:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

Kata kunci $schema menentukan versi spesifikasi JSON Schema mana yang diikuti oleh schema ini. Draft-07 adalah versi yang paling banyak diadopsi, meskipun Draft-2020-12 adalah yang terbaru. Kata kunci type di tingkat akar menentukan bahwa data yang divalidasi harus berupa objek JSON. Kata kunci properties mendefinisikan bidang yang diharapkan dan aturan validasinya. Kata kunci required mendaftar bidang mana yang harus ada dalam data. Dokumen JSON yang valid untuk schema ini akan terlihat seperti:

{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com"
}

Bidang age bersifat opsional (tidak ada di required) tetapi jika disediakan, harus berupa integer yang sama dengan atau lebih besar dari 0.

Versi JSON Schema

JSON Schema telah berevolusi melalui beberapa versi, masing-masing menambahkan fitur dan penyempurnaan baru. Draft-04 adalah versi pertama yang banyak diadopsi dan masih digunakan oleh banyak alat. Draft-07 memperkenalkan peningkatan signifikan termasuk validasi kondisional if/then/else, kata kunci const untuk pencocokan nilai tepat, dan contentMediaType untuk validasi data biner. Draft-2019-19 merestrukturisasi spesifikasi menjadi dokumen yang lebih kecil dan lebih fokus serta memperkenalkan unevaluatedProperties dan dependentRequired. Draft-2020-12 adalah versi terbaru, menambahkan prefixItems (menggantikan validasi tuple items), mekanisme kosakata baru, dan penanganan $id yang lebih baik. Saat membuat schema, Anda harus menggunakan draft terbaru yang didukung oleh alat Anda, dengan Draft-07 menjadi pilihan teraman untuk kompatibilitas maksimum.

Kata Kunci Validasi Umum

JSON Schema menyediakan kosakata yang kaya akan kata kunci validasi. Untuk string, Anda dapat memvalidasi minLength dan maxLength untuk batasan jumlah karakter, pattern untuk pencocokan ekspresi reguler, dan format untuk validasi semantik tipe data umum seperti alamat email, URI, tanggal, waktu, alamat IP, dan UUID. Untuk tipe numerik (integer dan number), Anda memiliki minimum dan maximum dengan varian eksklusif (exclusiveMinimum, exclusiveMaximum), dan multipleOf untuk pemeriksaan pembagian. Untuk array, kata kunci meliputi minItems dan maxItems untuk batasan ukuran, uniqueItems untuk mencegah entri duplikat, items untuk memvalidasi semua elemen terhadap schema, dan contains untuk memastikan setidaknya satu elemen cocok. Untuk objek, Anda memiliki properties untuk validasi tingkat bidang, additionalProperties untuk membatasi bidang yang tidak diketahui, required untuk bidang wajib, minProperties dan maxProperties untuk batasan ukuran, dependencies untuk persyaratan kondisional, dan propertyNames untuk memvalidasi nama bidang. Kata kunci enum berfungsi di semua tipe, menentukan set nilai yang diizinkan secara terbatas.

Validasi Lanjutan dengan Logika Kondisional

JSON Schema Draft-07 memperkenalkan kata kunci if, then, dan else untuk validasi kondisional. Ini memungkinkan Anda mengekspresikan batasan yang tergantung pada nilai bidang lain:

{
  "type": "object",
  "properties": {
    "type": { "enum": ["individual", "business"] },
    "taxId": { "type": "string" },
    "businessName": { "type": "string" }
  },
  "if": {
    "properties": { "type": { "const": "business" } },
    "required": ["type"]
  },
  "then": {
    "required": ["businessName", "taxId"]
  },
  "else": {
    "required": ["taxId"]
  }
}

Schema ini memerlukan businessName hanya ketika type adalah "business", sementara taxId diperlukan untuk kedua tipe. Validasi kondisional sangat kuat untuk memodelkan batasan data dunia nyata yang tergantung pada status atau tipe entitas.

Array dan Objek Bersarang

JSON Schema unggul dalam memvalidasi struktur data kompleks yang bersarang. Untuk array objek, Anda dapat mendefinisikan schema untuk item array:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "productId": { "type": "integer" },
      "quantity": { "type": "integer", "minimum": 1 },
      "price": { "type": "number", "minimum": 0 }
    },
    "required": ["productId", "quantity"]
  },
  "minItems": 1,
  "maxItems": 100
}

Anda dapat menggabungkan ini dengan validasi tuple menggunakan array schema untuk kata kunci items:

{
  "type": "array",
  "prefixItems": [
    { "type": "string" },
    { "type": "integer" },
    { "type": "boolean" }
  ],
  "additionalItems": false
}

Ini memvalidasi array di mana elemen pertama harus berupa string, kedua integer, dan ketiga boolean, tanpa elemen tambahan yang diizinkan.

Mendefinisikan Sub-Schema yang Dapat Digunakan Kembali dengan $defs

Untuk schema kompleks dengan struktur berulang, kata kunci $defs (disebut definitions di Draft-04) memungkinkan Anda mendefinisikan sub-schema yang dapat digunakan kembali:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "shippingAddress": { "$ref": "#/$defs/address" },
    "billingAddress": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zipCode": { "type": "string", "pattern": "^\\d{5}$" }
      },
      "required": ["street", "city"]
    }
  }
}

Menggunakan $ref untuk mereferensikan definisi menjaga schema tetap DRY (Don't Repeat Yourself) dan membuat pemeliharaan lebih mudah. Anda juga dapat mereferensikan file schema eksternal menggunakan nilai $ref berbasis URI, memungkinkan komposisi schema di berbagai file dan proyek.

Menggunakan Alat JSON Schema Validator

Menerapkan JSON Schema untuk memvalidasi data Anda sangat mudah dengan alat yang tepat. Alat JSON Schema Validator di Help2Code memungkinkan Anda menempelkan schema dan data JSON Anda, kemudian langsung melihat hasil validasi dengan pesan kesalahan yang mendetail. Validator mendukung Draft-07 dan memberikan umpan balik yang jelas untuk setiap kegagalan validasi, termasuk jalur tepat ke bidang yang tidak valid dan deskripsi batasan yang dilanggar. Ini sangat berharga untuk men-debug schema selama pengembangan dan untuk mempelajari cara kerja berbagai kata kunci validasi dalam praktik.

Integrasi dengan Bahasa Pemrograman

JSON Schema memiliki validator resmi dan yang didukung komunitas untuk hampir semua bahasa pemrograman. Dalam JavaScript, pustaka ajv adalah yang paling populer, menawarkan kinerja yang sangat baik dan dukungan untuk semua draft modern. Dalam Python, jsonschema menyediakan validasi komprehensif dengan penanganan kesalahan yang dapat disesuaikan. Dalam Java, pustaka everit-json-schema dan networknt/json-schema-validator banyak digunakan. Dalam Ruby, json-schema menawarkan validasi idiomatis Ruby dengan integrasi Rails. Dalam Go, gojsonschema menyediakan validasi yang kuat dengan pesan kesalahan deskriptif. Sebagian besar pustaka mendukung format kustom, kata kunci kustom, dan validasi asinkron, memungkinkan Anda memperluas JSON Schema di luar kemampuan bawaannya. Untuk pengembangan API, alat seperti OpenAPI/Swagger menggunakan JSON Schema sebagai fondasi untuk validasi permintaan dan respons mereka, menjadikan definisi schema sebagai langkah pertama dalam membangun API yang tangguh.

Praktik Terbaik untuk JSON Schema

Saat membuat JSON Schema, ikuti praktik terbaik ini. Selalu sertakan kata kunci $schema untuk menentukan versi draft, memastikan perilaku yang konsisten di seluruh validator. Gunakan additionalProperties: false pada objek untuk menangkap kesalahan ketik dan bidang yang tidak terduga selama validasi. Definisikan schema yang dapat digunakan kembali dengan $defs daripada menduplikasi struktur. Lebih suka format daripada pattern untuk tipe data umum seperti email dan tanggal — validator format lebih mudah dibaca dan seringkali lebih akurat. Jaga schema tetap ketat sesuai kebutuhan — lebih mudah melonggarkan validasi nanti daripada memperketatnya setelah data dengan struktur yang tidak terduga terakumulasi. Gunakan kata kunci default untuk mendokumentasikan nilai yang diharapkan tanpa mewajibkannya. Version schema Anda bersama dengan versi API Anda untuk menjaga kompatibilitas mundur.

Kesimpulan

JSON Schema adalah alat penting bagi setiap pengembang yang bekerja dengan data JSON. Ini menyediakan cara standar dan deklaratif untuk memvalidasi struktur data, mendokumentasikan format yang diharapkan, dan menangkap kesalahan sebelum mencapai produksi. Dari pemeriksaan tipe sederhana hingga validasi kondisional kompleks yang melibatkan objek dan array bersarang, JSON Schema diskalakan dengan kompleksitas data Anda. Dengan memasukkan validasi JSON Schema ke dalam alur kerja pengembangan Anda, Anda meningkatkan kualitas data, mengurangi bug, dan menciptakan integrasi yang lebih andal. Mulailah dengan alat JSON Schema Validator di Help2Code untuk bereksperimen dengan schema Anda sendiri, kemudian integrasikan pustaka validator ke dalam aplikasi Anda untuk validasi otomatis waktu nyata.