Validasi JSON Schema: Panduan Definitif

JSON Schema adalah kosakata untuk menganotasi dan memvalidasi dokumen JSON. Ini menyediakan kontrak untuk data Anda — mendefinisikan bentuk yang seharusnya, tipe apa yang diterima, dan field mana yang wajib. Jika Anda bekerja dengan API, file konfigurasi, atau data terstruktur apa pun, JSON Schema adalah alat penting dalam gudang senjata Anda.

Mengapa Menggunakan JSON Schema?

Tanpa validasi, data JSON adalah sebuah ketidakpastian. Anda mungkin menerima field usia sebagai string, email yang hilang, atau tanggal dalam format yang salah. JSON Schema menangkap masalah-masalah ini di batas sistem, sebelum data yang buruk menyebar ke seluruh sistem Anda.

Manfaat utama:

• Penegakan kontrak API: Validasi body request dan response secara otomatis
• Dokumentasi: Skema berfungsi sebagai dokumentasi hidup untuk struktur data Anda
• Pembuatan kode: Alat dapat menghasilkan tipe, form, dan skema database dari JSON Schema
• Pengujian: Validasi fixture pengujian dan data mock terhadap skema

Struktur Skema Dasar

Setiap JSON Schema dimulai dengan beberapa properti standar:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A registered user in the system",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"]
}

Gunakan JSON Formatter kami untuk mempercantik skema Anda agar mudah dibaca sebelum dibagikan ke tim Anda.

Batasan Tipe

JSON Schema mendukung enam tipe primitif:

Batasan String

{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[A-Za-z0-9]+$",
  "format": "email"
}

Format bawaan meliputi: email, uri, date, date-time, ipv4, ipv6, uuid, dan hostname.

Batasan Number

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,
  "multipleOf": 0.01
}

Validasi Array

Array dapat divalidasi untuk item, panjang, dan keunikannya:

{
  "type": "array",
  "items": { "type": "string", "format": "email" },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Untuk validasi tuple (array dengan panjang tetap dan tipe spesifik per posisi):

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "type": "boolean" }
  ],
  "items": false
}

Validasi Object

Object mendukung validasi properti, field wajib, dan kontrol properti tambahan:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "role": { "enum": ["admin", "editor", "viewer"] }
  },
  "required": ["name", "role"],
  "additionalProperties": false
}

Mengatur additionalProperties ke false adalah mode ketat yang menolak properti apa pun yang tidak didefinisikan dalam skema. Ini sangat berguna untuk API di mana Anda ingin menangkap kesalahan ketik pada nama field.

Kata Kunci Komposisi

JSON Schema mendukung penggabungan skema menggunakan operator logika:

allOf (AND)

Data harus valid terhadap semua subskema:

{
  "allOf": [
    { "$ref": "#/$defs/baseUser" },
    { "properties": { "role": { "const": "admin" } } }
  ]
}

oneOf (XOR)

Data harus valid terhadap tepat satu subskema:

{
  "oneOf": [
    { "properties": { "type": { "const": "email" }, "email": { "type": "string" } } },
    { "properties": { "type": { "const": "phone" }, "phone": { "type": "string" } } }
  ]
}

anyOf (OR)

Data harus valid terhadap setidaknya satu subskema.

Validasi Kondisional

Kata kunci if/then/else memungkinkan validasi kondisional:

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "properties": { "country": { "const": "US" } }
  },
  "then": {
    "properties": { "postalCode": { "pattern": "^[0-9]{5}(-[0-9]{4})?$" } }
  },
  "else": {
    "properties": { "postalCode": { "pattern": "^[A-Z0-9 -]+$" } }
  }
}

Referensi dan Penggunaan Ulang

Gunakan $ref untuk mereferensikan definisi yang dapat digunakan ulang:

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": { "type": "string" }
      },
      "required": ["street", "city", "country"]
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  }
}

Validasi dalam Praktik

JavaScript (Ajv)

const Ajv = require('ajv');
const ajv = new Ajv();

const validate = ajv.compile(schema);
const valid = validate(data);
if (!valid) console.log(validate.errors);

Python (jsonschema)

from jsonschema import validate, ValidationError

try:
    validate(instance=data, schema=schema)
except ValidationError as e:
    print(f"Validation error: {e.message}")

Untuk validasi cepat tanpa menyiapkan lingkungan pengembangan, tempel JSON dan skema Anda ke JSON Validator kami.

Contoh Dunia Nyata: Skema Respons API

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "enum": ["success", "error"] },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "name"]
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "page": { "type": "integer", "minimum": 1 },
        "perPage": { "type": "integer", "minimum": 1, "maximum": 100 },
        "total": { "type": "integer", "minimum": 0 }
      }
    }
  },
  "required": ["status", "data"]
}

FAQ

Apa perbedaan antara JSON Schema draft-07 dan 2020-12?

Draft 2020-12 memperkenalkan beberapa perbaikan: prefixItems menggantikan bentuk tuple dari items, $dynamicRef memungkinkan referensi yang lebih fleksibel, dan dukungan vocabulary memungkinkan ekstensi kustom. Untuk proyek baru, gunakan 2020-12. Untuk kompatibilitas dengan alat lama, draft-07 masih banyak didukung.

Bisakah JSON Schema memvalidasi JSON bersarang di dalam field string?

Tidak, secara langsung. JSON Schema memvalidasi struktur JSON yang sudah di-parse. Jika sebuah field berisi string JSON, Anda perlu mem-parse-nya terlebih dahulu dan memvalidasi secara terpisah. Beberapa validator menawarkan validator format kustom yang dapat menangani ini, tetapi itu bukan bagian dari standar.

Sumber Terkait

• JSON Formatter — Format dan percantik skema JSON Anda
• Cara Memvalidasi JSON — Kesalahan validasi JSON umum dan cara memperbaikinya
• Pola Desain JSON API — Membangun REST API yang lebih baik dengan JSON