Panduan Lengkap JSON Schema (Draft 7)

Apa itu JSON Schema?

Sebuah JSON Schema sendiri merupakan dokumen JSON yang mendeskripsikan bentuk data JSON lainnya. Gunakan untuk memvalidasi payload API, mendokumentasikan format yang diharapkan, menghasilkan kode (TypeScript, Go), dan menangkap data buruk sebelum mencapai logika Anda.

Keyword inti

Keyword type membatasi nilai menjadi string, number, boolean, null, object, atau array. properties dan required mendeskripsikan bentuk object; items mendeskripsikan elemen array.

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "number", "minimum": 0, "maximum": 150 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

Selain type: enum membatasi ke sekumpulan nilai tetap, const mengharuskan nilai yang persis, pattern mencocokkan regex, minLength/maxLength membatasi panjang string, dan additionalProperties: false melarang key yang tidak dikenal.

Schema API dunia nyata

Berikut schema untuk endpoint registrasi pengguna. Perhatikan bagaimana setiap batasan juga berfungsi sebagai dokumentasi, dan bagaimana required + additionalProperties: false membuat kontrak menjadi ketat.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "username": { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,30}$" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": "string", "minLength": 8 },
    "acceptTerms": { "type": "boolean", "const": true }
  },
  "required": ["username", "email", "password", "acceptTerms"],
  "additionalProperties": false
}

Praktik terbaik

Selalu deklarasikan $schema agar validator mengetahui draft yang Anda tuju. Tambahkan field description — field ini akan menjadi dokumentasi API langsung. Utamakan format (email, uri) daripada regex buatan sendiri. Gunakan additionalProperties: false untuk API yang ketat, tetapi izinkan ketika ekstensibilitas penting. Hindari schema yang bertingkat terlalu dalam — pecah dengan $ref dan definitions.