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

Deklarasikan $schema agar validator tahu draft yang Anda tuju. Tambahkan field description, karena editor dan dokumentasi API akan menampilkannya. Utamakan format (email, uri) daripada regex buatan sendiri. Gunakan additionalProperties: false untuk API yang ketat, dan biarkan terbuka saat ekstensibilitas penting. Jangan membuat schema bertingkat terlalu dalam; pecah dengan $ref dan definitions.