Validasi Skema MongoDB: Panduan Praktis dengan Contoh

MongoDB mungkin tanpa skema, tetapi bukan berarti data Anda harus berantakan.

Dalam artikel ini, Anda akan mempelajari segala hal mulai dari dasar-dasar validasi skema hingga kasus penggunaan tingkat lanjut menggunakan operator $jsonSchema. Anda akan mengeksplorasi cara menegakkan field wajib, membatasi tipe data, menerapkan pola, dan memvalidasi dokumen bertingkat.

Kami juga akan membahas cara kerja validasi saat insert dan update, cara memodifikasi koleksi yang sudah ada, dan kapan menggunakan level serta aksi validasi yang berbeda.

Pada akhirnya, Anda akan percaya diri menerapkan validasi skema pada koleksi MongoDB Anda, menjaga data tetap bersih dan dapat diprediksi, tanpa mengorbankan fleksibilitas yang menjadi ciri MongoDB. Anda juga dapat menonton video kami tentang validasi skema untuk mempelajari lebih lanjut.

Mengapa Validasi Skema Penting di MongoDB

Model dokumen dinamis MongoDB menawarkan kecepatan dan fleksibilitas dengan memungkinkan dokumen dalam koleksi yang sama memiliki field atau struktur yang berbeda. Ini merupakan keuntungan besar selama pengembangan awal atau iterasi cepat. Namun, fleksibilitas yang sama dapat dengan cepat menjadi beban, menghasilkan data yang tidak konsisten, tidak lengkap, atau tidak valid seiring pertumbuhan aplikasi Anda.

Di sinilah validasi skema berperan. Ini memungkinkan Anda mendefinisikan aturan untuk dokumen Anda—seperti field wajib, tipe data tertentu, atau struktur bertingkat—sembari tetap merangkul sifat fleksibel MongoDB.

Dalam artikel ini, Anda akan belajar cara menggunakan operator $jsonSchema yang kuat dari MongoDB untuk menerapkan aturan ini ke koleksi Anda. Baik Anda mencegah insert yang salah pada aplikasi baru atau menambahkan aturan validasi ke database lama, validasi skema membantu memastikan data Anda tetap bersih, kueri Anda tetap dapat diprediksi, dan aplikasi Anda tetap stabil.

Jika Anda baru bekerja dengan MongoDB dan Python, kurs pengantar MongoDB ini merupakan cara yang bagus untuk praktik langsung dengan kueri dan integrasi sebelum menyelami validasi skema.

Sebelum Anda Mulai

Agar panduan ini optimal, Anda memerlukan akses ke klaster MongoDB Atlas. Paket gratis sudah lebih dari cukup untuk diikuti.

Agar konsepnya jelas dan aplikatif, kami akan menggunakan dataset sampel MongoDB Atlas—khususnya database sample_mflix. Dataset ini mencakup koleksi seperti movies, comments, users, dan theaters, yang akan kami rujuk sepanjang artikel untuk menunjukkan setiap contoh. Dataset mencakup dokumen dengan field seperti objek bertingkat, array, string, angka, dan field opsional.

Muat dataset sampel (jika diperlukan)

1. Buka dasbor MongoDB Atlas Anda.

2. Pilih klaster Anda, klik tombol “…”, dan pilih Load Sample Dataset.

3. Tunggu beberapa menit hingga database sample_mflix tersedia.

Mulai Menggunakan Validasi Skema

Setelah dataset dimuat, sambungkan ke klaster Anda menggunakan MongoDB Shell (mongosh) atau MongoDB Compass, lalu beralih ke dataset:

use sample_mflixDidukung oleh

Mengeksplorasi dataset dengan findOne()

Mari kita periksa salah satu dokumen dari koleksi movies:

db.movies.findOne()Didukung oleh

Berikut versi sederhana dari apa yang mungkin Anda lihat:

Gambar 1. Kueri ini menggunakan findOne() untuk mengambil satu dokumen sampel dari koleksi movies di database sample_mflix. Hasilnya menampilkan berbagai field, termasuk title, year, genres, dan objek bertingkat seperti imdb dan tomatoes.viewer.

Dokumen ini berisi campuran nilai skalar, array, dan objek bertingkat, sehingga ideal untuk mendemonstrasikan berbagai teknik validasi. Pada bagian selanjutnya, kita akan membuat koleksi baru berdasarkan struktur ini dan mendefinisikan skema validasi pertama kita menggunakan $jsonSchema.

Kata kunci yang didukung, ekstensi, dan batasan

Validasi $jsonSchema MongoDB didasarkan pada spesifikasi JSON Schema Draft 4, dengan beberapa modifikasi dan penghilangan. Meskipun tidak semua fitur dari spesifikasi asli didukung, MongoDB menyertakan subset yang terfokus dan praktis untuk memvalidasi dokumen BSON.

Berikut beberapa kata kunci yang paling umum digunakan:

• bsonType: Kata kunci tipe khusus MongoDB (mis. "string", "int", "array", "object")
• required: Menentukan field yang harus ada
• minimum/maximum: Untuk validasi rentang numerik
• pattern: Untuk validasi format string menggunakan regular expression
• enum: Membatasi field pada sekumpulan nilai yang diizinkan
• items, minItems, maxItems: Untuk validasi array
• properties: Mendefinisikan aturan untuk field di dalam sebuah objek
• additionalProperties: Mengontrol apakah field ekstra (yang tidak didefinisikan) diperbolehkan

MongoDB sengaja menghilangkan beberapa fitur lanjutan dari JSON Schema penuh, seperti:

• Referensi skema ($ref).
• Logika kondisional (if/then/else).
• Operator komposisi (oneOf, allOf, anyOf).

Untuk daftar lengkap opsi yang didukung, lihat dokumen $jsonSchema MongoDB resmi.

Dalam artikel ini, kami akan berfokus pada kata kunci yang paling praktis dan banyak didukung, cukup untuk mencakup kebutuhan validasi dunia nyata yang umum tanpa kompleksitas berlebihan.

Untuk pemahaman yang lebih luas tentang bagaimana MongoDB masuk dalam lanskap NoSQL, jelajahi tutorial komprehensif ini.

Membuat Koleksi dengan Validasi Dasar

Sekarang setelah kita melihat struktur dokumen movies, mari buat koleksi baru yang menegakkan beberapa aturan dasar menggunakan $jsonSchema. Kita akan mulai dengan beberapa batasan umum:

• title: harus berupa string dan wajib ada
• year: harus berupa integer dan wajib ada
• genres: harus berupa array berisi string
• runtime: harus berupa integer positif

Kita akan menamai koleksi baru ini validated_movies.

Membuat koleksi

Jalankan perintah berikut untuk membuat koleksi dengan validasi:

db.createCollection("validated_movies", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["title", "year", "runtime"],
      properties: {
        title: {
          bsonType: "string",
          description: "must be a string and is required"
        },
        year: {
          bsonType: "int",
          minimum: 1888,
          description: "must be an integer >= 1888 (year of the first film)"
        },
        runtime: {
          bsonType: "int",
          minimum: 1,
          description: "must be a positive integer and is required"
        },
        genres: {
          bsonType: "array",
          items: {
            bsonType: "string"
          },
          description: "must be an array of strings"
        }
      }
    }
  },
  validationLevel: "strict",
  validationAction: "error"
});Didukung oleh

Menyisipkan dokumen yang valid

Sekarang, mari sisipkan dokumen yang mengikuti skema:

db.validated_movies.insertOne({
  title: "Inception",
  year: 2010,
  runtime: 148,
  genres: ["Action", "Sci-Fi", "Thriller"]
});Didukung oleh

✅ Ini seharusnya berhasil.

Menyisipkan dokumen yang tidak valid

Coba sisipkan dokumen yang tidak memiliki field title:

db.validated_movies.insertOne({
  year: 2020,
  runtime: 95,
  genres: ["Drama"]
});Didukung oleh

❌ Ini akan gagal dengan error validasi karena title wajib ada.

Gambar 2. Perintah pertama menyisipkan dokumen film yang valid ke koleksi validated_movies, memenuhi semua field dan tipe data yang diwajibkan. Perintah kedua mencoba menyisipkan dokumen tanpa field title yang diwajibkan, sehingga menghasilkan error validasi.

Bekerja dengan Koleksi yang Sudah Ada

Anda tidak perlu memulai dari nol untuk menggunakan validasi skema. MongoDB memungkinkan Anda menerapkan aturan validasi ke koleksi yang sudah ada menggunakan perintah collMod. Ini sangat berguna saat Anda ingin menambahkan struktur ke dataset lama tanpa memengaruhi dokumen yang sudah ada.

Di bagian ini, kita akan menerapkan validator ke koleksi movies dari database sample_mflix.

Menambahkan validator dengan collMod

Mari kita tegakkan aturan dasar: Setiap dokumen film harus memiliki field title bertipe string.

db.runCommand({
  collMod: "movies",
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["title"],
      properties: {
        title: {
          bsonType: "string",
          description: "must be a string and is required"
        }
      }
    }
  },
  validationLevel: "moderate",
  validationAction: "warn"
});Didukung oleh

Memeriksa aturan validasi pada koleksi

Setelah memodifikasi koleksi movies menggunakan perintah collMod, Anda mungkin ingin memastikan aturan validasi mana yang saat ini aktif.

Untuk memeriksa validator skema saat ini, jalankan:

db.getCollectionInfos({ name: "movies" })[0].options.validatorDidukung oleh

Ini mengembalikan objek $jsonSchema yang mendefinisikan aturan validasi pada koleksi. Ini adalah cara yang berguna untuk memverifikasi bahwa konfigurasi Anda diterapkan dengan benar, terutama setelah beralih mode seperti warn ke error, atau memperbarui struktur field yang diwajibkan.

Memahami validationLevel dan validationAction

• validationLevel: "moderate": Hanya memvalidasi dokumen yang sedang disisipkan atau diperbarui. Dokumen yang sudah ada dan tidak sesuai skema tidak akan memicu error.

• validationAction: "warn": Alih-alih menolak penulisan yang tidak valid, MongoDB mencatat peringatan. Ini berguna di produksi saat Anda ingin memantau pelanggaran skema sebelum menegakkannya.

Coba sisipkan dokumen yang melanggar skema:

db.movies.insertOne({
  year: 2023
});Didukung oleh

Anda akan melihat peringatan di log, tetapi penulisan akan berhasil. Anda dapat mengubah aksinya menjadi "error" nanti untuk menegakkan aturan secara ketat setelah Anda yakin.

Gambar 3. Perintah insertOne() berhasil menambahkan dokumen yang melanggar aturan skema, karena aksi validasi diatur ke "warn." MongoDB menerima penulisan, tetapi field title yang hilang akan memicu error validasi jika "error" diterapkan.

Memvalidasi Dokumen Bertingkat dan Array

Dokumen MongoDB sering kali mencakup struktur bertingkat, seperti objek di dalam objek dan array nilai. Untungnya, $jsonSchema mendukung validasi keduanya. Mari jelajahi cara menerapkan aturan pada subdokumen dan isi array menggunakan field dari koleksi movies.

Memvalidasi dokumen bertingkat

Dalam koleksi movies, setiap dokumen menyertakan objek tertanam imdb dengan field seperti rating, votes, dan id. Mari terapkan aturan yang memastikan:

• imdb adalah objek (jika ada).
• imdb.rating adalah angka antara 0 dan 10.

Berikut cara Anda mendefinisikannya:

db.createCollection("validated_nested", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      properties: {
        imdb: {
          bsonType: "object",
          properties: {
            rating: {
              bsonType: "double",
              minimum: 0,
              maximum: 10,
              description: "Must be a number between 0 and 10"
            }
          }
        }
      }
    }
  }
});Didukung oleh

Menguji dokumen bertingkat

✅ Insert yang valid:

db.validated_nested.insertOne({
  title: "Interstellar",
  imdb: { rating: 8.6 }
});Didukung oleh

❌ Insert yang tidak valid (rating di luar rentang):

db.validated_nested.insertOne({
  title: "Bad Movie",
  imdb: { rating: 12.5 }
});Didukung oleh

Ini akan memicu error validasi karena rating lebih besar dari 10.      Gambar 4. Operasi insert ini gagal karena field rating di dalam objek imdb yang bertingkat melebihi nilai maksimum yang diizinkan, yaitu 10, seperti yang didefinisikan dalam skema. MongoDB melempar error validasi akibat pelanggaran aturan $jsonSchema.

Memvalidasi array

Anda juga dapat menegakkan batasan pada array. Misalnya, Anda ingin memastikan bahwa:

• genres adalah array berisi string.
• Array harus memiliki setidaknya satu item.

Tambahkan ini ke skema Anda:

genres: {
  bsonType: "array",
  minItems: 1,
  items: {
    bsonType: "string"
  },
  description: "Must be a non-empty array of strings"
}Didukung oleh

Mengombinasikan Beberapa Batasan

Dalam aplikasi dunia nyata, dokumen Anda sering kali perlu memenuhi beberapa aturan validasi sekaligus—mencakup field wajib, nilai yang diizinkan, tipe, dan struktur bertingkat. Dengan $jsonSchema, Anda dapat dengan mudah menggabungkan beberapa batasan dalam satu definisi skema.

Mari kita buat contoh yang lebih lengkap menggunakan struktur dokumen movies. Kita akan menegakkan aturan berikut:

• title: wajib, harus berupa string
• year: wajib, integer, ≥ 1888
• rated: opsional, tetapi harus sesuai dengan kumpulan nilai yang telah ditentukan
• genres: harus berupa array berisi string dan tidak boleh kosong
• imdb.rating: angka antara 0 dan 10
• tomatoes.viewer.rating: opsional, angka antara 0 dan 5

Membuat koleksi tervalidasi

db.createCollection("validated_full", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["title", "year"],
      properties: {
        title: {
          bsonType: "string",
          description: "Title is required and must be a string"
        },
        year: {
          bsonType: "int",
          minimum: 1888,
          description: "Year must be an integer >= 1888"
        },
        rated: {
          enum: ["G", "PG", "PG-13", "R", "NC-17"],
          description: "Must be a valid MPAA rating"
        },
        genres: {
          bsonType: "array",
          minItems: 1,
          items: { bsonType: "string" },
          description: "Must be a non-empty array of strings"
        },
        imdb: {
          bsonType: "object",
          properties: {
            rating: {
              bsonType: "double",
              minimum: 0,
              maximum: 10,
              description: "IMDB rating must be between 0 and 10"
            }
          }
        },
        tomatoes: {
          bsonType: "object",
          properties: {
            viewer: {
              bsonType: "object",
              properties: {
                rating: {
                  bsonType: "double",
                  minimum: 0,
                  maximum: 5,
                  description: "Viewer rating must be between 0 and 5"
                }
              }
            }
          }
        }
      }
    }
  }
});Didukung oleh

Menyisipkan dokumen yang valid: 

db.validated_full.insertOne({
  title: "The Matrix",
  year: 1999,
  rated: "R",
  genres: ["Action", "Sci-Fi"],
  imdb: { rating: 8.7 },
  tomatoes: { viewer: { rating: 4.2 } }
});Didukung oleh

Menyisipkan dokumen yang tidak valid:

db.validated_full.insertOne({
  title: "Untitled Project",
  year: 2025,
  rated: "Unrated",
  genres: [],
  imdb: { rating: 15 },
  tomatoes: { viewer: { rating: 6.1 } }
});Didukung oleh

Ini akan gagal karena:

• Nilai rated tidak valid.
• Array genres kosong.
• imdb.rating melebihi 10.
• tomatoes.viewer.rating melebihi 5.

Gambar 5. Operasi insert ini gagal karena beberapa pelanggaran skema di koleksi validated_full. Field rated berisi nilai yang tidak diizinkan oleh enum, genres adalah array kosong yang melanggar aturan minItems, imdb.rating melebihi maksimum 10 dan bertipe salah, serta tomatoes.viewer.rating melebihi maksimum yang diizinkan yaitu 5. MongoDB menolak insert dengan error validasi rinci.

Penjelasan Level dan Aksi Validasi

MongoDB memberi Anda kontrol terperinci atas bagaimana dan kapan validasi skema diterapkan. Saat mendefinisikan aturan validasi, dua opsi memengaruhi perilaku database Anda:

• validationLevel: Kapan aturan harus ditegakkan
• validationAction: Apa yang terjadi ketika dokumen tidak sesuai aturan

validationLevel

Opsi ini mengontrol operasi mana yang tunduk pada validasi skema.

• strict: Semua insert dan update harus sesuai dengan skema. Ini adalah mode default dan paling aman.
• moderate: Hanya dokumen yang sedang disisipkan atau diperbarui yang divalidasi. Dokumen yang sudah ada, meskipun tidak valid, dibiarkan apa adanya.

Kapan digunakan:

• Gunakan strict untuk koleksi baru di mana Anda ingin sepenuhnya menegakkan skema sejak awal.
• Gunakan moderate saat menerapkan validasi ke koleksi yang sudah berisi data lama atau tidak terstruktur.

validationAction

Opsi ini mengontrol bagaimana MongoDB merespons ketika dokumen melanggar aturan validasi.

• error: Operasi tulis ditolak, dan error validasi dikembalikan.
• warn: Tulis diterima, tetapi peringatan dicatat secara internal oleh server.

Penting: Di MongoDB Atlas, peringatan dari warn tidak terlihat oleh pengguna—Anda tidak akan melihatnya di UI atau log standar.

Kapan digunakan:

• Gunakan warn di pengembangan atau selama peluncuran bertahap untuk memantau pelanggaran tanpa memblokir penulisan.
• Beralih ke error saat Anda yakin aplikasi Anda menulis dokumen yang valid dan ingin menegakkan skema secara ketat.

Contoh: Beralih dari Warn ke Error

Misalkan Anda memulai dengan ini:

db.runCommand({
  collMod: "validated_full",
  validationAction: "warn",
  validationLevel: "moderate"
});Didukung oleh

Setelah mengamati perilaku aplikasi Anda, Anda dapat beralih ke penegakan ketat:

db.runCommand({
  collMod: "validated_full",
  validationAction: "error",
  validationLevel: "strict"
});Didukung oleh

Gambar 6. Dua perintah collMod digunakan untuk memodifikasi perilaku validasi koleksi validated_full. Yang pertama menetapkan validationAction ke "warn" dan validationLevel ke "moderate," memungkinkan dokumen tidak valid disisipkan sambil mencatat peringatan internal. Perintah kedua beralih ke penegakan ketat dengan mengatur validationAction ke "error" dan validationLevel ke "strict," memastikan semua insert dan update harus sepenuhnya mematuhi skema yang ditentukan.

Kini, setiap insert atau update yang tidak valid akan diblokir dengan pesan error.

Kesalahan Umum dan Tips Debugging

Saat bekerja dengan validasi skema, kesalahan kecil dapat menyebabkan error yang membingungkan—atau lebih buruk lagi, dokumen melewati aturan Anda tanpa terdeteksi. Berikut beberapa masalah yang paling sering terjadi dan cara menghindarinya:

Nilai bsonType yang salah

Salah satu kesalahan paling umum saat menggunakan $jsonSchema adalah membingungkan tipe JSON dengan “bsonType” MongoDB. Sementara "string" dan "array" cukup jelas, tipe lain seperti angka dan boolean bisa jadi rumit.

Misalnya:

• Gunakan "int" atau "long" untuk bilangan bulat.
• Gunakan "double" untuk bilangan pecahan.
• Gunakan "bool" (bukan "boolean") untuk nilai benar/salah.
• Gunakan "object" untuk subdokumen (bukan "dict" atau "map").
• Gunakan "array" untuk daftar.

Jika Anda tidak yakin tipe apa yang disimpan sebuah field, Anda bisa memeriksa dokumen menggunakan typeof di Mongo shell atau meninjau data menggunakan MongoDB Compass.

Field wajib hilang pada pembaruan parsial

Saat menggunakan $set, validasi hanya memeriksa field yang diubah. Jika Anda mengharapkan pemeriksaan skema penuh, pastikan Anda melakukan penggantian dokumen penuh atau menggunakan validationLevel: "strict" dengan logika aplikasi yang menegakkan struktur penuh.

Array kosong lolos saat tidak seharusnya

Jika Anda lupa menentukan minItems, array kosong akan lolos:

	genres: {
	  bsonType: "array",
	  items: { bsonType: "string" }
	}
	// Accepts empty arrays by defaultDidukung oleh

Gunakan minItems: 1 untuk memastikan setidaknya ada satu nilai.

Tidak ada error pada mode warn

Seperti dibahas sebelumnya, validationAction: "warn" tidak memblokir penulisan atau menampilkan error di MongoDB Atlas. Ini hanya mencatat secara internal, sehingga validasi mungkin terlihat “tidak berfungsi.”

Gunakan mode "error" selama pengembangan atau lingkungan pengujian untuk menangkap masalah sejak dini.

Path field bertingkat tidak diperiksa jika objek induk hilang

Jika imdb.rating diwajibkan, tetapi imdb sama sekali tidak ada, MongoDB tidak akan memeriksa rating.

Untuk menegakkan validasi pada field bertingkat, pastikan objek induknya diwajibkan atau memiliki bsonType: "object".

Mengkueri atau memperbarui dokumen yang tidak sesuai skema

Setelah menerapkan validasi ke koleksi yang sudah ada, sering kali membantu untuk mengidentifikasi dokumen yang tidak sesuai dengan skema baru. Anda bisa melakukannya dengan menggunakan operator $jsonSchema dalam kueri dengan $nor atau $not.

Contoh: Temukan dokumen tidak valid di koleksi movies

Misalkan skema Anda mewajibkan title bertipe "string." Untuk menemukan dokumen yang tidak cocok, Anda dapat menjalankan:

db.movies.find({
  $nor: [
    { $jsonSchema: {
        bsonType: "object",
        required: ["title"],
        properties: {
          title: { bsonType: "string" }
        }
      }
    }
  ]
});Didukung oleh

Ini akan mengembalikan dokumen yang tidak memiliki title atau memiliki title dengan tipe yang salah.

Gambar 7. Kueri ini menggunakan $nor dengan $jsonSchema untuk menemukan dokumen di koleksi movies yang tidak memiliki field title bertipe string. Hasilnya menunjukkan dokumen dengan _id: 683ce0050bd195c35e417534 yang hanya berisi field year, mengonfirmasi bahwa dokumen tersebut melanggar skema yang mewajibkan title. Teknik ini berguna untuk mengidentifikasi dokumen tidak valid sebelum menegakkan aturan validasi yang lebih ketat.

Anda juga dapat menggunakan pendekatan ini untuk:

• Mengaudit dokumen lama sebelum beralih dari "warn" ke "error."
• Membersihkan atau memperbaiki dokumen tidak valid secara terprogram.
• Menghasilkan laporan tentang kepatuhan skema.

Ringkasan: Data Bersih Tanpa Mengorbankan Fleksibilitas

Desain tanpa skema MongoDB adalah salah satu kekuatannya yang terbesar, namun bukan berarti Anda harus membiarkan data tanpa pemeriksaan. Dengan $jsonSchema, Anda dapat mendefinisikan aturan validasi yang kuat untuk menegakkan struktur sembari memanfaatkan fleksibilitas MongoDB.

Sepanjang artikel ini, Anda telah mempelajari cara:

• Membuat koleksi dengan aturan validasi.
• Menerapkan batasan pada koleksi baru dan yang sudah ada.
• Menggunakan validasi bertingkat untuk objek dan array.
• Mengonfigurasi mode dan aksi validasi.
• Mendebug dan menyempurnakan skema Anda dengan percaya diri.

Baik membangun aplikasi baru maupun menambahkan struktur ke sistem lama, validasi skema memberi Anda alat untuk melindungi data tanpa memperlambat pengembangan.

Langkah Lanjut dan Sumber Daya

Ingin mendalami lebih jauh? Lihat sumber daya berikut:

• Dokumentasi Validasi Skema MongoDB 
• Dokumentasi JSON Schema MongoDB
• Data sampel di MongoDB Atlas

Sedang mempersiapkan wawancara? Pertanyaan MongoDB teratas ini akan menguji pemahaman Anda tentang topik seperti validasi skema dan lainnya. Ingin memvalidasi keahlian Anda? Panduan sertifikasi ini merincikan semua yang perlu Anda ketahui untuk meraih sertifikasi MongoDB.

Ingat, mulai dari yang kecil, uji dengan "warn," dan beralih ke "error" setelah Anda yakin—diri Anda di masa depan (dan data Anda) akan berterima kasih.