Data JSON Terlihat Benar, tetapi Aplikasi Masih Error? Ini Peran JSON Schema
Utomo Parwito 8/06/2026
TechCorner.ID - Data JSON dapat terlihat rapi, bisa dibuka tanpa masalah, dan dinyatakan benar oleh parser. Namun, aplikasi tetap dapat mengalami error ketika tipe data tidak sesuai, properti penting hilang, atau struktur yang diterima berbeda dari format yang diharapkan sistem.
Sebuah layanan, misalnya, mungkin mengirimkan harga sebagai teks, padahal aplikasi penerima mengharapkannya dalam bentuk angka. JSON tersebut tetap sah secara sintaks, tetapi tidak cocok dengan aturan data yang dibutuhkan. Kesalahan seperti ini dapat memicu kegagalan validasi, masalah sinkronisasi, respons API yang tidak konsisten, hingga bug yang sulit ditemukan.
Di sinilah JSON Schema berperan. Teknologi ini memungkinkan developer mendefinisikan tipe data, properti wajib, batas nilai, susunan array, pola teks, dan berbagai aturan lain dalam sebuah kontrak yang dapat diperiksa secara otomatis. Situs resmi JSON Schema menyediakan dokumentasi, spesifikasi, contoh, dan direktori tooling untuk membantu penerapannya.
Ringkasan Cepat
Data JSON yang benar secara sintaks belum tentu sesuai dengan kebutuhan aplikasi. JSON Schema berfungsi sebagai kontrak yang menentukan struktur, tipe data, properti wajib, dan batasan nilai sehingga kesalahan dapat ditemukan sebelum data diproses lebih lanjut.
Apa Itu JSON Schema?
JSON Schema adalah vocabulary atau bahasa deklaratif yang digunakan untuk menjelaskan struktur dan batasan sebuah dokumen JSON. Dokumen yang berisi aturan disebut schema, sedangkan data JSON yang diperiksa berdasarkan aturan tersebut disebut instance.
Melalui schema, developer dapat menentukan bahwa sebuah data harus berbentuk object, memiliki properti tertentu, menggunakan tipe nilai yang sesuai, atau memenuhi batasan yang telah ditetapkan. Aturan tersebut kemudian dibaca oleh validator untuk menentukan apakah data dapat diterima oleh aplikasi.
Sebagai contoh, sistem toko online dapat menetapkan bahwa setiap produk harus mempunyai ID berupa bilangan bulat, nama berupa teks, dan harga berupa angka nonnegatif. Ketika data produk masuk melalui API, validator akan membandingkan isinya dengan schema yang tersedia.
Data akan dinyatakan valid apabila seluruh aturan yang berlaku terpenuhi. Jika ada tipe data yang salah, properti wajib tidak tersedia, atau nilai berada di luar batas, validator dapat menolaknya dan menampilkan informasi mengenai bagian yang bermasalah.
Mengapa JSON yang Valid Masih Bisa Membuat Aplikasi Error?
JSON pada dasarnya hanya mengatur cara data ditulis. Parser akan memeriksa tanda kurung, tanda petik, koma, pasangan nama dan nilai, serta susunan object atau array. Parser tidak otomatis memahami kebutuhan bisnis sebuah aplikasi.
Perhatikan contoh berikut:
{
"name": "Keyboard Mekanis",
"price": "sembilan ratus ribu"
}Dokumen tersebut merupakan JSON yang sah. Properti name dan price ditulis dengan struktur yang benar. Akan tetapi, aplikasi dapat gagal memprosesnya apabila price seharusnya berupa angka yang akan digunakan untuk menghitung total pembayaran.
Masalah serupa dapat terjadi ketika properti penting tidak dikirim, nilai kosong masuk ke field yang seharusnya wajib, atau nama properti berubah tanpa pemberitahuan. Dari sudut pandang parser, datanya mungkin tetap valid. Dari sudut pandang aplikasi, isinya tidak sesuai kontrak.
JSON Schema menutup celah antara validitas sintaks dan validitas struktur. Dengan aturan yang terdokumentasi, pengirim dan penerima data mempunyai acuan yang sama mengenai bentuk data yang diperbolehkan.
Cara Kerja JSON Schema dalam Memeriksa Data
1. Schema Mendefinisikan Kontrak Data
Developer membuat dokumen schema yang berisi sejumlah keyword. Keyword type digunakan untuk menentukan tipe nilai, properties mendefinisikan field dalam object, sedangkan required menentukan properti yang harus tersedia.
Aturan dapat dibuat sederhana maupun bertingkat. Sebuah properti dapat mempunyai subschema sendiri, kemudian di dalamnya terdapat ketentuan tambahan untuk panjang teks, batas angka, bentuk array, atau object lain.
2. Instance Menyediakan Data Aktual
Instance adalah data JSON yang akan diperiksa. Satu schema dapat digunakan berulang kali untuk memvalidasi banyak instance selama seluruh data tersebut diharapkan mengikuti struktur yang sama.
Schema produk, misalnya, dapat digunakan untuk memeriksa data yang dikirim melalui formulir admin, respons API, file impor, aplikasi mobile, atau proses sinkronisasi dengan layanan lain.
3. Validator Membandingkan Data dengan Schema
JSON Schema membutuhkan validator atau library yang sesuai dengan bahasa pemrograman dan lingkungan aplikasi. Validator membaca dialect yang digunakan, menjalankan aturan, kemudian menghasilkan status valid atau tidak valid.
Ketika validasi gagal, validator biasanya memberikan lokasi kesalahan, keyword yang tidak terpenuhi, serta pesan penjelas. Format dan tingkat detail pesan tersebut dapat berbeda antara satu library dan library lainnya.
Versi JSON Schema yang Perlu Digunakan
Saat artikel ini diperbarui pada Agustus 2026, Draft 2020-12 masih menjadi versi terbaru yang tercantum pada halaman spesifikasi resmi JSON Schema. Versi tersebut membawa sejumlah perubahan penting dibandingkan draft sebelumnya, termasuk penggunaan prefixItems untuk tuple, dukungan $dynamicRef dan $dynamicAnchor, serta panduan untuk menggabungkan beberapa schema dalam sebuah compound schema document.
Setiap schema sebaiknya menyatakan dialect yang digunakan melalui keyword $schema pada bagian root:
{
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Deklarasi tersebut membantu validator, editor kode, dan anggota tim memahami kumpulan keyword beserta perilaku yang berlaku. Tanpa deklarasi versi, sebuah library mungkin meminta konfigurasi terpisah atau menggunakan asumsi default yang belum tentu sesuai dengan proyek.
Dukungan setiap validator terhadap Draft 2020-12 juga perlu diperiksa. Sebagian library mungkin masih mengutamakan Draft-07 atau hanya mendukung sebagian fitur dari versi yang lebih baru.
Contoh JSON Schema untuk Data Produk
Berikut contoh sederhana untuk memvalidasi data produk:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/product.schema.json",
"title": "Data Produk",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string",
"minLength": 3
},
"price": {
"type": "number",
"minimum": 0
},
"status": {
"type": "string",
"enum": ["active", "inactive"]
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["productId", "name", "price"],
"additionalProperties": false
}Schema tersebut menetapkan bahwa data utama harus berbentuk object. Properti productId wajib berupa integer dengan nilai minimal 1, sedangkan name harus berupa string yang memiliki setidaknya tiga karakter.
Properti price hanya menerima angka dengan nilai nol atau lebih. Sementara itu, status dibatasi pada dua pilihan, yaitu active dan inactive.
Setiap anggota dalam array tags harus berupa string. Penggunaan additionalProperties: false membuat validator menolak properti lain yang tidak didefinisikan pada bagian properties dalam subschema yang sama.
Data berikut sesuai dengan aturan:
{
"productId": 101,
"name": "Keyboard Mekanis",
"price": 899000,
"status": "active",
"tags": ["peripheral", "gaming"]
}Validasi dapat gagal apabila productId dikirim sebagai teks, harga bernilai negatif, nama terlalu pendek, atau muncul properti yang tidak diizinkan.
Keyword Penting yang Sering Digunakan
1. type
Keyword type menentukan tipe data yang diterima. Tipe utama yang umum digunakan meliputi object, array, string, number, integer, boolean, dan null.
Pemilihan tipe harus disesuaikan dengan cara data akan diproses. Nomor telepon, misalnya, lebih tepat disimpan sebagai string karena dapat diawali angka nol dan tidak digunakan untuk perhitungan matematika.
2. properties dan required
properties digunakan untuk mendefinisikan schema bagi setiap field di dalam object. Sementara itu, required menentukan field yang harus hadir.
Perlu dipahami bahwa required hanya memeriksa keberadaan properti. Keyword tersebut tidak otomatis memastikan string berisi teks atau nilainya tidak berupa null.
Untuk menolak string kosong, tambahkan aturan seperti:
{
"type": "string",
"minLength": 1
}
Apabila string dan nilai null sama-sama diperbolehkan, tipe dapat ditulis sebagai berikut:
{
"type": ["string", "null"]
}Properti yang tidak tersedia berbeda dari properti yang tersedia dengan nilai null. Perbedaan ini penting dalam formulir, database, pembaruan parsial, dan respons API.
3. minimum, maximum, dan multipleOf
Nilai numerik dapat dibatasi menggunakan minimum, maximum, exclusiveMinimum, exclusiveMaximum, dan multipleOf.
Aturan tersebut berguna untuk membatasi usia, harga, jumlah pesanan, persentase, koordinat, atau nilai numerik lain yang mempunyai rentang tertentu.
4. minLength, maxLength, dan pattern
String dapat diperiksa berdasarkan panjang dan pola tertentu. minLength menetapkan jumlah karakter minimum, sedangkan maxLength menentukan batas maksimum.
Keyword pattern menggunakan regular expression untuk memeriksa pola teks. Aturan ini dapat digunakan untuk kode produk, format identitas internal, awalan tertentu, atau struktur teks yang relatif konsisten.
5. items dan prefixItems
Keyword items mengatur schema yang berlaku terhadap anggota array. Jika semua elemen harus berupa string, schema dapat ditulis seperti berikut:
{
"type": "array",
"items": {
"type": "string"
}
}Pada Draft 2020-12, prefixItems digunakan untuk mendefinisikan aturan berdasarkan posisi awal elemen dalam array atau tuple. Perubahan ini perlu diperhatikan saat memigrasikan schema dari draft lama.
6. enum dan const
enum membatasi nilai ke beberapa pilihan yang sudah ditentukan. Keyword ini cocok untuk status, kategori, metode pembayaran, jenis akun, atau kode tertentu.
Sementara itu, const mengharuskan sebuah nilai tetap. Penggunaannya berguna ketika object tertentu harus memiliki penanda jenis atau versi yang tidak boleh berubah.
7. allOf, anyOf, oneOf, dan not
JSON Schema menyediakan keyword untuk menggabungkan beberapa aturan. allOf mengharuskan data memenuhi seluruh subschema, sedangkan anyOf menerima data yang cocok dengan satu atau lebih subschema.
oneOf mengharuskan data cocok dengan tepat satu subschema. Apabila dua aturan sekaligus terpenuhi, validasi tetap gagal. Karena itu, setiap cabang perlu dibuat cukup berbeda agar tidak terjadi tumpang tindih.
Keyword not digunakan untuk menolak data yang memenuhi schema tertentu.
8. $id, $defs, dan $ref
Keyword $id memberikan identifier sekaligus base URI pada schema. $defs dapat digunakan untuk menyimpan subschema yang akan dipakai kembali, sedangkan $ref menunjuk ke definisi internal atau schema eksternal.
Pendekatan modular membantu menghindari pengulangan. Aturan alamat, profil pengguna, metode pembayaran, atau informasi perangkat dapat didefinisikan satu kali kemudian digunakan pada beberapa bagian.
Hal Penting tentang Keyword format
Keyword format digunakan untuk memberikan makna semantik pada string, misalnya date-time, email, hostname, IPv4, IPv6, URI, atau UUID.
{
"type": "string",
"format": "email"
}Namun, pada dialect default Draft 2020-12, format tidak boleh langsung diasumsikan selalu bekerja sebagai aturan penolakan. Sebagian validator memperlakukannya sebagai anotasi, sementara validator lain menyediakan opsi khusus untuk mengaktifkan pemeriksaan format sebagai assertion.
Developer perlu membaca dokumentasi library dan mengaktifkan pemeriksaan format apabila dibutuhkan. Validasi format juga tidak menggantikan verifikasi bisnis. String yang menyerupai alamat email belum tentu benar-benar aktif atau dimiliki pengguna.
Apakah default Otomatis Mengisi Nilai?
Keyword default merupakan anotasi yang memberi tahu nilai bawaan yang disarankan. Standar JSON Schema tidak mewajibkan validator untuk otomatis menambahkan nilai tersebut ke instance.
{
"type": "string",
"default": "inactive"
}Beberapa library memang menyediakan fitur pengisian nilai default, tetapi perilaku tersebut merupakan kemampuan tambahan dari implementasi. Hasilnya tidak boleh dianggap sama pada semua validator.
Hal serupa berlaku untuk normalisasi, pemangkasan spasi, konversi string menjadi angka, atau perubahan tipe data. JSON Schema berfokus pada deskripsi dan evaluasi data, bukan otomatis melakukan seluruh proses transformasi.
Manfaat JSON Schema untuk Pengembangan Aplikasi
1. Menjaga Kontrak Data API
Frontend, backend, aplikasi mobile, dan layanan pihak ketiga dapat merujuk pada definisi struktur yang sama. Perubahan format lebih mudah ditinjau sebelum menyebabkan gangguan pada integrasi yang sudah berjalan.
2. Menemukan Kesalahan Lebih Awal
Validasi dapat dijalankan ketika data masuk, dalam pengujian otomatis, atau pada proses build. Kesalahan tipe data dan field yang hilang dapat ditemukan sebelum data masuk ke database atau diteruskan ke layanan lain.
3. Mendukung Dokumentasi dan Tooling
Schema yang dilengkapi title, description, dan examples dapat dimanfaatkan untuk dokumentasi, bantuan editor, generator formulir, atau pembuatan data uji. Dukungan akhirnya bergantung pada tooling yang dipilih.
4. Mengurangi Duplikasi Aturan
Penggunaan $defs dan $ref memungkinkan satu definisi digunakan kembali. Ketika struktur berubah, tim tidak perlu memperbarui salinan aturan yang tersebar di banyak file.
5. Mempermudah Kolaborasi
Schema dapat menjadi rujukan bersama bagi developer frontend, backend, quality assurance, DevOps, dan tim integrasi. Kontrak tertulis mengurangi ketergantungan pada asumsi dan komunikasi informal.
Keterbatasan yang Tetap Perlu Dipahami
JSON Schema bukan pengganti seluruh logika bisnis aplikasi. Schema dapat memastikan harga tidak negatif, tetapi tidak mengetahui apakah harga tersebut sama dengan nilai terbaru di katalog.
Schema juga tidak otomatis memastikan sebuah ID tersedia di database, kode promo masih aktif, stok barang mencukupi, atau pengguna mempunyai izin untuk melakukan tindakan tertentu. Pemeriksaan semacam itu tetap perlu dijalankan pada lapisan aplikasi.
Kompatibilitas antar-draft juga harus diperhatikan. Draft-07 dan Draft 2020-12 tidak identik. Perbedaan dapat muncul pada aturan array, referensi dinamis, vocabulary, dan sejumlah keyword lainnya.
Oleh karena itu, pergantian validator atau peningkatan versi sebaiknya disertai pengujian terhadap data valid maupun tidak valid.
Praktik Terbaik Menggunakan JSON Schema
1. Deklarasikan Dialect secara Eksplisit
Sertakan $schema agar versi dan perilaku schema tidak ambigu. Jangan hanya mengandalkan pengaturan default dari validator.
2. Gunakan Identifier yang Stabil
Tetapkan $id yang konsisten dan tidak mudah berubah. Identifier menjadi penting ketika schema dipecah menjadi beberapa file atau saling terhubung melalui $ref.
3. Buat Aturan Secukupnya
Mulailah dari struktur yang benar-benar dibutuhkan aplikasi. Aturan yang terlalu longgar kurang memberi perlindungan, tetapi schema yang terlalu ketat dapat menyulitkan pengembangan dan kompatibilitas data.
4. Uji Kasus Positif dan Negatif
Jangan hanya menguji data yang benar. Buat juga skenario ketika field hilang, tipe salah, string kosong, angka melewati batas, nilai null muncul, array tidak sesuai, atau properti asing ditambahkan.
5. Periksa Dukungan Validator
Pastikan library mendukung dialect yang digunakan, resolusi $ref, vocabulary yang dibutuhkan, serta konfigurasi format. Gunakan versi dan pengaturan yang konsisten pada lingkungan pengembangan, pengujian, dan produksi.
Link Resmi JSON Schema
Untuk mempelajari spesifikasi, contoh, dan tooling yang tersedia, gunakan halaman resmi berikut:
- Situs Utama JSON Schema
- Dokumentasi JSON Schema
- Spesifikasi JSON Schema
- Panduan Belajar JSON Schema
- Direktori Validator dan Tooling
Sebelum memilih validator, periksa dukungan draft, lisensi, dokumentasi, aktivitas pemeliharaan, kemampuan resolusi referensi, serta bentuk pesan error yang dihasilkan.
Pelajari Integrasi API dan Otomatisasi Data
JSON Schema semakin berguna ketika sebuah sistem bertukar data melalui API, webhook, atau workflow otomatis. Untuk memahami bagaimana data berpindah di antara aplikasi dan layanan digital, baca juga artikel n8n sebagai platform workflow automation untuk integrasi aplikasi dan API.
Temukan pembahasan lain mengenai aplikasi, developer tools, API, dan sistem digital melalui Hub Software TechCorner.ID.
Ikuti Panduan Software Bersama TechCorner.ID
Kontrak data yang jelas dapat membantu aplikasi lebih mudah diuji, dikembangkan, dan diintegrasikan dengan layanan lain. Terus ikuti TechCorner.ID untuk mendapatkan pembahasan seputar software, API, otomatisasi, keamanan digital, dan perkembangan teknologi yang relevan bagi pengguna Indonesia.
Kesimpulan
Data JSON yang benar secara sintaks belum tentu mempunyai struktur yang dapat diproses oleh aplikasi. Tipe data yang keliru, properti wajib yang hilang, atau nilai yang berada di luar batas tetap dapat menimbulkan error meskipun parser tidak menemukan masalah.
JSON Schema menyediakan cara terstruktur untuk mendefinisikan kontrak data. Melalui keyword seperti type, properties, required, items, enum, $defs, dan $ref, developer dapat menentukan bentuk data yang diperbolehkan dan menemukan ketidaksesuaian lebih awal.
Penerapannya dapat membantu menjaga konsistensi API, memperjelas dokumentasi, mendukung pengujian, dan mengurangi perbedaan pemahaman antartim. Meski demikian, schema tetap perlu dipadukan dengan logika bisnis serta validator yang mendukung dialect proyek.
Untuk proyek baru, gunakan dialect yang dinyatakan secara eksplisit, mulai dari aturan yang paling penting, lalu tambahkan kompleksitas secara bertahap. Pendekatan ini membuat validasi lebih kuat tanpa menjadikan schema sulit dipelihara.
FAQ Singkat
1. Apakah JSON Schema sama dengan JSON?
Tidak. JSON adalah format untuk menulis dan bertukar data, sedangkan JSON Schema digunakan untuk menjelaskan serta memvalidasi struktur data tersebut.
2. Apakah JSON yang valid pasti bisa diproses aplikasi?
Belum tentu. Data dapat benar secara sintaks, tetapi tetap menggunakan tipe, properti, atau nilai yang tidak sesuai dengan kebutuhan aplikasi.
3. Apakah JSON Schema hanya digunakan untuk API?
Tidak. Teknologi ini juga dapat digunakan untuk file konfigurasi, formulir, pengujian, dokumentasi, pipeline data, editor, dan pertukaran data antarsistem.
4. Apa versi JSON Schema terbaru?
Saat artikel ini diperbarui pada Agustus 2026, versi terbaru yang tercantum pada halaman spesifikasi resmi adalah Draft 2020-12.
5. Apakah required membuat nilai tidak boleh kosong?
Tidak. required hanya memastikan properti hadir. Gunakan aturan seperti minLength untuk menolak string kosong dan pastikan tipe tidak mencakup null jika nilai null tidak diperbolehkan.
6. Apakah format email selalu diperiksa validator?
Tidak selalu. Perilakunya bergantung pada dukungan dan konfigurasi validator. Beberapa implementasi memerlukan pengaktifan pemeriksaan format sebagai assertion.
7. Apakah default otomatis mengisi nilai yang hilang?
Tidak secara standar. default merupakan anotasi. Pengisian nilai otomatis hanya tersedia apabila validator atau library menyediakan fitur tambahan tersebut.
