JSON Schema Validator

Apa itu JSON Schema dan mengapa penting?

JSON (JavaScript Object Notation) adalah bahasa universal untuk API web, file konfigurasi, dan pertukaran data. Namun JSON mentah tidak punya sistem tipe bawaan — sebuah field bisa berupa string hari ini dan angka besok, dan satu-satunya cara mengetahui ketidakcocokan itu adalah crash saat runtime atau bug data yang halus. JSON Schema mengisi celah itu: ia adalah kosakata deklaratif untuk mendeskripsikan struktur dan batasan yang diharapkan dari sebuah dokumen JSON, divalidasi terhadap data sebenarnya saat runtime.

Tim developer memakai JSON Schema untuk memvalidasi payload permintaan API sebelum diproses, menegakkan bentuk file konfigurasi yang dimuat saat startup, membuat dokumentasi dan form UI secara otomatis dari satu sumber kebenaran, serta menjaga konsistensi kontrak antar microservice. OpenAPI — standar untuk dokumentasi REST API — dibangun langsung di atas JSON Schema, menjadikannya standar validasi data yang paling banyak dipakai di web.

Versi draft JSON Schema: Draft-07, Draft 2019-09, dan Draft 2020-12

JSON Schema telah melalui beberapa draft spesifikasi. Draft-07, dirilis tahun 2018, tetap menjadi versi yang paling banyak didukung di semua pustaka validator utama dan merupakan dialek yang dipakai OpenAPI 3.0. Draft ini memperkenalkan keyword validasi bersyarat if/then/else yang kuat, anotasi properti readOnly/writeOnly, dan keyword content encoding. Jika Anda menulis schema hari ini dan tidak butuh fitur terbaru, Draft-07 adalah pilihan paling aman untuk kompatibilitas ekosistem maksimal.

Draft 2020-12 adalah spesifikasi stabil terkini dan memperkenalkan beberapa perubahan signifikan: keyword items digantikan oleh prefixItems untuk validasi tuple, referensi dinamis memakai $dynamicRef alih-alih $recursiveRef, dan keyword baru unevaluatedProperties serta unevaluatedItems memberikan kontrol lebih presisi atas konten tambahan. Gunakan Draft 2020-12 hanya jika Anda memakai OpenAPI 3.1 atau butuh fitur spesifik tersebut — ekosistem validator yang lebih luas masih menyusul dukungan penuhnya.

Keyword utama JSON Schema yang perlu dipahami

Keyword type menegakkan tipe data: string, number, integer, boolean, array, object, atau null. required mendaftar properti yang wajib ada dalam objek. properties memetakan setiap nama properti ke sub-schema-nya sendiri. pattern menerapkan ekspresi reguler pada nilai string. minimum, maximum, minLength, dan maxLength membatasi rentang angka dan string. enum membatasi nilai pada sekumpulan nilai yang diizinkan; const membatasinya pada satu nilai saja.

Keyword komposisi memungkinkan Anda membangun aturan kompleks dari blok sederhana: allOf bertindak seperti AND logika, anyOf seperti OR, dan oneOf seperti XOR. Keyword not membalik sebuah schema. Keyword if/then/else memungkinkan validasi bersyarat — aturan berbeda berlaku tergantung apakah data memenuhi schema if. Bersama-sama, keyword ini memungkinkan Anda mengekspresikan hampir semua aturan validasi tanpa menulis kode imperatif kustom.

JSON Schema dalam produksi: kontrak API dan pipeline CI

Dalam sistem produksi, validasi JSON Schema berjalan di sisi server atau dalam pipeline CI memakai pustaka seperti Ajv (JavaScript/Node.js), jsonschema (Python), atau Newtonsoft.Json (C#). Schema disimpan dalam version control bersama kode aplikasi sehingga perubahan kontrak ditinjau dan dilacak seperti perubahan lainnya. Perubahan yang merusak — menghapus field wajib, mempersempit tipe — tertangkap dalam code review sebelum sampai ke produksi dan merusak konsumen.

Tool berbasis browser ini ideal untuk merancang dan men-debug schema secara iteratif sebelum melakukan commit. Tempel data Anda, tulis schema Anda, klik Validate, baca pesan error yang detail, dan sempurnakan — tanpa server, tanpa npm install, tanpa bolak-balik. Validator juga mem-pretty-print JSON Anda pada setiap proses validasi, menjadikannya JSON formatter dan schema tester gabungan yang praktis. Setelah schema Anda tervalidasi di sini, langsung masukkan ke spesifikasi OpenAPI atau konfigurasi aplikasi Anda.

Contoh praktis: memvalidasi respons API

Misalkan API Anda mengembalikan objek user. JSON Schema yang memvalidasinya mungkin mewajibkan id berupa integer, name berupa string yang tidak kosong, email berupa string yang cocok dengan pola email, dan role opsional berupa string dari enum 'admin', 'editor', dan 'viewer'. Menetapkan additionalProperties ke false memastikan API Anda tidak pernah diam-diam mengembalikan field tak terdokumentasi yang mungkin secara tidak sengaja diandalkan oleh konsumen di hilir.

Fitur if/then/else memungkinkan aturan bersyarat — misalnya, jika role adalah 'admin' maka array permissions wajib ada, jika tidak maka dilarang. Aturan komposisional ini memungkinkan satu schema mencakup beberapa bentuk objek yang valid tanpa menduplikasi definisi properti. Menulis dan menguji schema tersebut di sini sebelum menyematkannya ke basis kode Anda menghemat banyak waktu debugging di produksi. Gunakan preset contoh bawaan (User Profile, Product, Address) untuk memulai secara instan.

Bagaimana UtiloKit dibandingkan dengan validator JSON Schema lain

Sebagian besar tool JSON Schema validator online terbagi dalam dua kategori: pembuat schema visual dan validator API sisi server. jsonschema.net memaksa Anda melalui UI klik-dan-pilih untuk menyusun schema — membantu untuk pemula yang mempelajari struktur schema, tapi lambat bagi developer yang sudah tahu keyword apa yang mereka butuhkan dan hanya ingin menguji schema yang sudah mereka tulis. Anda tidak bisa menempel JSON Draft-07 mentah secara langsung dan beriterasi cepat.

jsonschemavalidator.net, dibangun di atas pustaka Newtonsoft.Json milik Microsoft, melaporkan error memakai path properti dan kode error .NET yang terasa asing bagi developer JavaScript. Pesan errornya benar tapi dibingkai seputar model objek .NET, bukan path JSON pointer yang akan dilihat kode Node.js Anda. Tool seperti Stoplight dan SwaggerHub memvalidasi schema sebagai bagian dari dokumen OpenAPI lengkap dan membutuhkan setup proyek serta akun.

Validator UtiloKit berjalan di atas mesin Ajv yang sama yang menggerakkan sebagian besar aplikasi Node.js, Express, dan Fastify. Pesan error, path JSON pointer, dan perilaku keyword cocok persis dengan lingkungan produksi Anda — dan berjalan gratis di browser Anda tanpa akun, tanpa upload, tanpa batas ukuran file, dan tanpa batas penggunaan harian.

Sejarah singkat JSON Schema: dari draft IETF menjadi standar de facto

JSON itu sendiri diformalkan oleh Douglas Crockford dan dipublikasikan pada 2001, awalnya sebagai format pertukaran data ringan yang diekstrak dari JavaScript. Format ini dengan cepat menggeser XML dalam API web karena sintaksnya yang minimal dan pemetaan langsung ke struktur data umum. Tapi kesederhanaan JSON juga menjadi keterbatasan: format ini tidak punya sistem tipe native, tidak ada batasan bawaan, dan tidak ada cara mendeskripsikan seperti apa dokumen yang valid. Celah itulah yang melahirkan JSON Schema. Kris Zyp menulis spesifikasi JSON Schema pertama pada 2009 sebagai IETF Internet Draft, menyediakan kosakata untuk menganotasi dan memvalidasi dokumen JSON memakai JSON itu sendiri — tanpa sintaks baru yang dibutuhkan.

Sejak 2009, JSON Schema berkembang melalui beberapa draft spesifikasi yang tidak saling kompatibel. Draft-03 (2010) dan draft-04 (2013) membangun set keyword fondasi dan memperkenalkan mekanisme referensi $ref. Draft-06 dan draft-07 (2017–2018) menyempurnakan keyword khusus tipe dan menambahkan validasi bersyarat if/then/else. Draft 2019-09 menata ulang spesifikasi menjadi kosakata modular dan memperkenalkan $anchor untuk anchor bernama. Draft 2020-12 — versi rekomendasi saat ini — menggantikan bentuk tuple items dengan prefixItems, memperkenalkan $dynamicRef untuk schema rekursif, dan menambahkan unevaluatedProperties serta unevaluatedItems untuk semantik closed-schema yang lebih presisi. Keyword $schema di root dokumen mengidentifikasi draft mana yang menjadi target sebuah schema — misalnya, "$schema": "https://json-schema.org/draft/2020-12/schema" — memungkinkan validator menerapkan aturan dialek yang benar.

Meski draft 2020-12 adalah spesifikasi terkini, draft-07 tetap menjadi versi yang paling banyak diimplementasikan dalam praktik. Ekosistem yang lebih luas — Ajv di JavaScript, jsonschema di Python, Newtonsoft.Json di C#, dan Spesifikasi OpenAPI 3.0 — menstandarkan diri pada draft-07 dan biaya migrasi meng-upgrade pustaka schema besar cukup tinggi. Penting dicatat bahwa JSON Schema masih berstatus IETF Internet Draft, artinya belum menjadi standar RFC resmi. Meski begitu ia berfungsi sebagai standar de facto untuk validasi data JSON: ia tertanam di OpenAPI, dirujuk dalam mesin IntelliSense VS Code, dipakai oleh AWS CDK, dan divalidasi dalam pipeline CI di sebagian besar perusahaan teknologi besar. Organisasi JSON Schema memelihara spesifikasi ini di json-schema.org dengan model governance terbuka.

Keyword inti JSON Schema: referensi praktis

Sistem tipe dalam JSON Schema mencakup tujuh tipe primitif: string, number, integer, boolean, object, array, dan null. Keyword type bisa menerima satu string atau sebuah array — "type": ["string", "null"] adalah pola standar untuk field yang boleh null, membuatnya eksplisit bahwa sebuah field boleh secara sah tidak ada atau null alih-alih mewajibkan sebuah nilai. Validasi objek memakai properties untuk mendefinisikan sub-schema per properti, required untuk mendaftar nama properti wajib, dan additionalProperties untuk mengontrol key yang tidak dikenal. Menetapkan additionalProperties: false membuat schema "tertutup" yang menolak properti apa pun yang tidak secara eksplisit terdaftar di bawah properties — kontrak paling ketat untuk payload API. patternProperties memetakan pola regex ke sub-schema untuk key yang dinamai secara dinamis. minProperties dan maxProperties membatasi berapa banyak key yang boleh dimiliki sebuah objek.

Validasi array memakai items (draft-07) atau prefixItems (draft 2020-12) untuk sub-schema per elemen. Ketika items berupa satu schema, setiap elemen harus memenuhinya — berguna untuk daftar homogen. Ketika items berupa array of schema di draft-07, setiap posisi divalidasi terhadap schema yang sesuai — ini adalah validasi tuple, di mana urutan penting. minItems dan maxItems membatasi panjang array; uniqueItems: true menegakkan semantik set. Keyword validasi string mencakup minLength, maxLength, dan pattern untuk batasan regex. Keyword format memberikan petunjuk semantik — nilai seperti "email", "date-time", "uri", dan "ipv4" — tapi secara default hanya berupa anotasi. Validator harus dikonfigurasi secara eksplisit untuk menegakkan format (di Ajv, kirim { formats: "full" } atau install ajv-formats). Validasi angka memakai minimum, maximum, exclusiveMinimum, exclusiveMaximum, dan multipleOf untuk batasan kelipatan.

Keyword komposisi adalah yang memberi JSON Schema daya ekspresifnya. allOf mewajibkan data memenuhi setiap sub-schema yang terdaftar sekaligus — AND logika, sering dipakai untuk menumpuk schema dasar dengan schema ekstensi. anyOf mewajibkan setidaknya satu sub-schema lulus — OR logika, dipakai untuk tipe union. oneOf mewajibkan tepat satu sub-schema lulus — XOR logika, berguna ketika sub-schema saling eksklusif dan Anda ingin menandai input yang ambigu. Keyword not membalik hasil sub-schema, memungkinkan pola pengecualian. $ref merujuk sub-schema yang didefinisikan di tempat lain dalam dokumen — biasanya di bawah $defs (draft 2020-12) atau key definitions lama — menjaga schema tetap DRY dan modular. Bersama-sama, primitif ini memungkinkan Anda mengekspresikan secara presisi aturan struktural apa pun yang jika tidak akan membutuhkan ratusan baris kode validasi imperatif.

Ajv, ekosistem validator, dan JSON Schema di luar JavaScript

Ajv (Another JSON Validator), dibuat oleh Evgeny Poberezkin dan dirilis sebagai open source, adalah validator JSON Schema JavaScript tercepat dan paling banyak dipakai. Inovasi arsitektur utamanya adalah kompilasi just-in-time: Ajv mengompilasi schema menjadi fungsi JavaScript native saat pertama kali dipakai, artinya validasi berikutnya terhadap schema yang sama nyaris tidak memiliki overhead parsing. Benchmark secara konsisten menunjukkan Ajv memproses sekitar satu juta validasi per detik untuk schema tipikal pada perangkat keras biasa. Ajv mendukung draft-07 hingga draft 2020-12 dan merupakan mesin validasi yang tertanam dalam dukungan schema bawaan Fastify, dalam pustaka konstruk AWS CDK, dan dalam ekosistem tooling OpenAPI. Mulai Ajv v8, strict mode aktif secara default — ia menolak schema yang mengandung keyword tidak dikenal, penggunaan exclusiveMinimum yang ambigu, dan pola yang sering menandakan kesalahan, membuatnya jauh lebih sulit mengirim schema yang diam-diam rusak ke produksi. Validator JSON Schema UtiloKit berjalan di atas Ajv di browser lewat build UMD-nya, sehingga hasil validasi di sini cocok persis dengan apa yang akan dihasilkan backend Anda yang bertenaga Ajv.

Validasi JSON Schema tidak terbatas pada JavaScript. Developer Python memakai pustaka jsonschema (dipelihara oleh Julian Berman), yang mendukung draft 3 hingga 2020-12 dan terintegrasi rapi dengan lapisan validasi data FastAPI. Java punya dua implementasi utama: everit-org/json-schema dan networknt/json-schema-validator, yang terakhir lebih aktif dipelihara dan menjadi opsi yang compliant draft 2020-12 dipakai dalam layanan Spring Boot enterprise. Developer Go memakai qri-io/jsonschema dan xeipuuv/gojsonschema. .NET punya Newtonsoft.Json.Schema dan JsonSchema.Net yang lebih baru. Setiap implementasi bahasa memiliki perbedaan perilaku kecil — terutama seputar keyword opsional format dan struktur pesan error — itulah mengapa menguji schema terhadap pustaka validator spesifik yang dipakai stack produksi Anda adalah satu-satunya cara andal mengonfirmasi perilakunya.

JSON Schema juga menjadi bagian penting dari tooling developer di luar validasi runtime. VS Code dan editor lain membaca field $schema dalam file seperti package.json, tsconfig.json, file workflow GitHub Actions, dan output AWS CDK untuk menyediakan IntelliSense, autocomplete, dan highlight error inline real-time saat Anda mengetik. OpenAPI 3.0 memakai subset JSON Schema — disebut OpenAPI Schema Object — untuk definisi permintaan dan respons; OpenAPI 3.1 selaras penuh dengan draft 2020-12. Tool contract testing API seperti Dredd, Spectral, dan Pact memakai JSON Schema untuk menegaskan bahwa respons API langsung sesuai dengan kontrak yang terdokumentasi, menangkap regresi secara otomatis dalam CI. Tool code generation TypeScript seperti quicktype dan json-schema-to-typescript membuat definisi interface TypeScript dari JSON Schema, menjaga validasi runtime dan tipe compile-time tetap sinkron dari satu sumber kebenaran. Bahkan mesin database pun telah mengadopsi format ini: PostgreSQL 14+ bisa memvalidasi kolom jsonb terhadap ekspresi JSON Schema, dan MongoDB menerapkan dialek JSON Schema ala MongoDB untuk validasi schema tingkat koleksi — artinya kosakata schema yang sama yang Anda uji di sini mengalir melalui seluruh stack, dari autocomplete IDE hingga API gateway hingga penyimpanan database.