Pemverifikasian Skema JSON Mendeteksi Pelanggaran Kontrak API Sebelum Dikirim

Jika API Anda mengembalikan field yang tidak ada menurut skema, atau menerima badan permintaan dengan properti wajib yang hilang, maka terjadi pelanggaran kontrak. Bug ini bersifat halus, sering diam, dan terkenal mahal untuk ditemukan di produksi. Validasi JSON Schema adalah lapisan yang menangkap kesalahan ini lebih awal — lebih dekat dengan tempat mereka muncul.

Panduan ini menjelaskan bagaimana JSON Schema bekerja, validator mana yang sebaiknya digunakan di Node.js, Python, dan AWS, serta cara menjaga agar skema Anda tetap sesuai dengan kenyataan.

Apa Itu JSON Schema

JSON Schema adalah bahasa untuk menggambarkan struktur dokumen JSON. Ini bukan kode — ini metadata. Anda menulis skema yang menyatakan bagaimana objek JSON yang valid terlihat, lalu menjalankan validator terhadapnya.

Skema itu sendiri adalah dokumen JSON. Contoh minimal:

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

Itu saja. Berikan ini ke validator dengan payload JSON apa saja, dan Anda akan mendapatkan hasil lulus atau daftar kegagalan yang terstruktur.

Kata Kunci Inti

Sejumlah kata kunci mencakup kebutuhan validasi dunia nyata:

additionalProperties: false memperoleh perhatian khusus. Ini adalah kata kunci yang membuat skema menjadi ketat — setiap properti yang tidak didefinisikan dalam properties memicatatkan kesalahan validasi. Ini diatur secara default, yang berarti kebanyakan skema menerima field yang tidak valid secara diam-diam kecuali Anda memilih untuk mengaktifkannya.

Skema Lengkap: Permintaan Pendaftaran Pengguna

Berikut adalah skema JSON lengkap untuk permintaan endpoint pendaftaran. Ini adalah jenis skema yang Anda tulis sekali dan diperiksa di setiap lapisan yang mengakses endpoint tersebut.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

Anda dapat menguji ini secara interaktif terhadap setiap payload menggunakan IO Tools JSON Schema Validator sebelum mengintegrasikannya ke dalam kode Anda.

Validasi Badan Permintaan API

Express + AJV

AJV adalah validator JSON Schema tercepat untuk Node.js. Berikut adalah middleware Express yang memvalidasi badan permintaan sebelum mencapai handler Anda:

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

function validateBody(schema) {
  const validate = ajv.compile(schema);
  return (req, res, next) => {
    if (validate(req.body)) {
      return next();
    }
    res.status(400).json({
      error: "Validation failed",
      details: validate.errors,
    });
  };
}

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true menginstruksikan AJV untuk mengumpulkan semua kesalahan dalam dokumen, bukan berhenti pada kesalahan pertama — berguna ketika Anda ingin mengembalikan semua kegagalan validasi ke klien sekaligus.

Perhatikan pola Nginx: Anda perlu

Di Python, FastAPI menggunakan Pydantic di balik layarnya dan secara otomatis menghasilkan JSON Schema dari annotasi tipe Anda. Jika Anda bekerja dengan skema JSON dari sumber eksternal, bukan dari model Pydantic, jsonschema adalah library standar:

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

try:
    validate(instance=request_body, schema=schema)
except ValidationError as e:
    return {"error": e.message}, 400

AWS API Gateway

API Gateway mendukung validasi badan permintaan secara native. Anda mendefinisikan model (yang merupakan dokumen JSON Schema) dan menghubungkannya ke metode Anda sebagai REQUEST_BODY validator. Permintaan yang gagal validasi ditolak pada tingkat gateway — sebelum fungsi Lambda pernah dijalankan. Ini menghilangkan kelas kesalahan handler dan mengurangi panggilan cold-start untuk lalu lintas yang tidak valid.

Skema yang Dapat Digunakan Ulang dengan $ref dan $defs

Ketika beberapa skema berbagi struktur yang sama — seperti alamat, jumlah uang, atau objek pagination — definisikan sekali di $defs dan acuannya dengan $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

Untuk proyek yang lebih besar, skema berada di file terpisah dan $ref mengacu ke URL. Validator yang mendukung kata kunci dan resolusi URL dapat memuat skema secara lambat atau dari registry — AJV menangani ini melalui $id Drift Skema addSchema().

Drift skema terjadi ketika skema dan API aktual berbeda. Ini lebih umum daripada yang terdengar: skema ditulis sekali, API berkembang, dan tidak ada yang memperbarui skema.

Gejala-gejalanya halus. Sebuah field diubah nama di kode tetapi tidak di skema — validasi tetap lolos karena

tidak diatur ke false. Sebuah field wajib menjadi opsional dalam praktik karena kode tidak lagi memeriksanya — skema tetap menyatakan bahwa ia wajib, namun tidak ada yang menyadari hingga klien mengirim permintaan tanpa field tersebut. additionalProperties Mendeteksi drift membutuhkan menganggap validasi skema sebagai tes, bukan sebagai periksa runtime. Beberapa tim mengotomatiskan ini dengan tes snapshot terhadap fixture respons nyata. Yang lain menjalankan validator skema di CI terhadap serangkaian permintaan API yang tercatat. Poinnya adalah bahwa skema harus diuji secara teratur, bukan hanya di-deploy sekali.

JSON Schema dan OpenAPI

OpenAPI (dulu Swagger) menggunakan JSON Schema untuk menggambarkan badan permintaan dan respons, tetapi dengan beberapa modifikasi. Versi sebelumnya (OpenAPI 2.0, 3.0) menggunakan subset dari JSON Schema dengan ekstensi. OpenAPI 3.1 lebih sesuai dengan JSON Schema draft 2020-12, sehingga skema hampir dapat saling digunakan.

Perbedaan praktisnya: OpenAPI menutupi skema dalam dokumen yang lebih besar yang juga menggambarkan jalur, operasi, autentikasi, dan server. JSON Schema sendiri hanya merupakan kontrak validasi. Jika Anda membangun API berbasis skema, Anda bisa menulis skema JSON untuk setiap endpoint, memvalidasikannya, dan kemudian memindahkan skema tersebut langsung ke dokumen OpenAPI.

Menghasilkan Skema dari Data yang Ada

Menulis skema secara manual bekerja baik untuk API baru. Untuk API yang sudah ada dengan perilaku yang tidak terdokumentasikan, seringkali lebih cepat untuk menghasilkan skema dari payload nyata, lalu memperketatnya.

(Python) dan

Alat seperti genson (Node.js) menerima objek JSON sebagai contoh dan menghasilkan draft skema. Skema yang dihasilkan hampir selalu terlalu lemah — semua menjadi opsional, tidak ada generate-schema — tetapi memberikan titik awal. Anda kemudian menambahkan additionalProperties: false , memperketat requireddefinisi, dan menambahkan type kendala ketika nilai dibatasi. enum Pendekatan ini juga membantu saat memasukkan API pihak ketiga tanpa dokumentasi skema. Jalankan beberapa respons melalui generator skema, gabungkan hasilnya, dan Anda akan memiliki kontrak yang dapat digunakan untuk validasi.

Validasi JSON Schema harus ada di setiap lapisan yang menerima data terstruktur — middleware HTTP, konsumen antrian pesan, jalur penulisan ke database. Semakin awal pelanggaran kontrak terdeteksi, semakin murah untuk diperbaiki. Sebuah

validator skema JSON online mengizinkan Anda untuk memperbincangkan skema terhadap payload nyata sebelum memutuskan untuk mengintegrasikan ke library, yang membuatnya menjadi langkah pertama yang tepat untuk semua pekerjaan validasi. mengizinkan Anda membangun skema secara prototipe terhadap payload nyata sebelum memutuskan untuk mengintegrasikan dengan library, yang membuatnya langkah pertama yang tepat untuk setiap pekerjaan validasi.

Anda mungkin juga menyukai

Pembuatan Palet Warna: Membangun Palet Lengkap Dari Satu Hex:

Baca selengkapnya "

Diterbitkan pada 12 Mei 2026

Verifikasi Tanda Tangan PDF: Apa yang Perlu Diketahui Pengembang

Baca selengkapnya "

Diterbitkan pada 10 Mei 2026

Markdown vs HTML: Kapan Harus Menggunakan Masing-Masing untuk Dokumentasi, README, dan API

Baca selengkapnya "

Diterbitkan pada 9 Mei 2026

Parameter UTM: Cara Mencatat Kampanye Pemasaran Tanpa Menebak

Baca selengkapnya "

Diterbitkan pada 8 Mei 2026