MongoDB-schema-validatie: een praktische gids met voorbeelden

MongoDB mag dan schemaloos zijn, maar dat betekent niet dat je data een rommeltje hoeft te zijn.

In dit artikel leer je alles van de basis van schema-validatie tot geavanceerde use-cases met de operator $jsonSchema. Je ontdekt hoe je verplichte velden afdwingt, datatypes beperkt, patronen toepast en geneste documenten valideert. 

We behandelen ook hoe validatie werkt tijdens inserts en updates, hoe je bestaande collecties aanpast en wanneer je verschillende validatieniveaus en -acties gebruikt. 

Aan het einde kun je met vertrouwen schema-validatie toepassen op je MongoDB-collecties, zodat je data schoon en voorspelbaar blijft, zonder de flexibiliteit op te geven waar MongoDB om bekendstaat. Bekijk ook onze video over schema-validatie voor meer info.

Waarom schema-validatie in MongoDB belangrijk is

Het dynamische documentmodel van MongoDB biedt snelheid en flexibiliteit doordat documenten in dezelfde collectie andere velden of structuren mogen hebben. Dat is een groot voordeel in vroege ontwikkelfases of bij snelle iteraties. Maar diezelfde flexibiliteit kan ook een nadeel worden naarmate je applicatie groeit, met inconsistente, onvolledige of ongeldige data als gevolg.

Daar komt schema-validatie om de hoek kijken. Hiermee definieer je regels voor je documenten—zoals verplichte velden, specifieke datatypes of geneste structuren—terwijl je nog steeds de flexibele aard van MongoDB benut.

In dit artikel leer je hoe je MongoDB’s krachtige operator $jsonSchema gebruikt om deze regels op je collecties toe te passen. Of je nu misvormde inserts wilt voorkomen in een nieuwe applicatie of validatieregels wilt toevoegen aan een legacy-database, schema-validatie helpt om je data schoon te houden, je queries voorspelbaar te maken en je applicatie stabiel te houden.

Als je nieuw bent met MongoDB en Python, is dit introductiecursus MongoDB een geweldige manier om praktisch aan de slag te gaan met queries en integraties voordat je in schema-validatie duikt.

Voordat je begint

Om het meeste uit deze gids te halen, heb je toegang nodig tot een MongoDB Atlas-cluster. De gratis laag is ruim voldoende om mee te doen.

Om de concepten zo duidelijk en toepasbaar mogelijk te maken, gebruiken we een MongoDB Atlas-voorbeelddataset—specifiek de database sample_mflix. Deze dataset bevat collecties zoals movies, comments, users en theaters, waarnaar we in dit artikel zullen verwijzen om elk voorbeeld te demonstreren. De dataset bevat documenten met velden zoals geneste objecten, arrays, strings, getallen en optionele velden.

Laad de voorbeelddataset (indien nodig)

1. Ga naar je MongoDB Atlas-dashboard.

2. Kies je cluster, klik op de “…”-knop en selecteer Load Sample Dataset.

3. Wacht een paar minuten totdat de database sample_mflix beschikbaar is.

Aan de slag met schema-validatie

Zodra je dataset is geladen, maak je verbinding met je cluster via MongoDB Shell (mongosh) of MongoDB Compass en schakel je over naar de dataset:

use sample_mflixMogelijk gemaakt door

De dataset verkennen met findOne()

Laten we een van de documenten uit de collectie movies bekijken:

db.movies.findOne()Mogelijk gemaakt door

Hier is een vereenvoudigde versie van wat je zou kunnen zien:

Figuur 1. Deze query gebruikt findOne() om één voorbeeld­document op te halen uit de collectie movies in de database sample_mflix. Het resultaat toont verschillende velden, waaronder title, year, genres en geneste objecten zoals imdb en tomatoes.viewer.

Dit document bevat een mix van scalars, arrays en geneste objecten, waardoor het ideaal is om diverse validatietechnieken te demonstreren. In de volgende sectie maken we een nieuwe collectie op basis van deze structuur en definiëren we ons eerste validatieschema met $jsonSchema.

Ondersteunde keywords, extensies en beperkingen

MongoDB’s $jsonSchema-validatie is gebaseerd op de JSON Schema Draft 4-specificatie, met enkele aanpassingen en weglatingen. Hoewel niet alle features uit de originele spec worden ondersteund, biedt MongoDB een gefocuste en praktische subset die geschikt is voor het valideren van BSON-documenten.

Hier zijn enkele veelgebruikte keywords:

• bsonType: MongoDB-specifiek typekeyword (bijv. "string", "int", "array", "object")
• required: Geeft aan welke velden aanwezig moeten zijn
• minimum/maximum: Voor numerieke bereikvalidatie
• pattern: Voor stringformaat-validatie met reguliere expressies
• enum: Beperkt een veld tot een set toegestane waarden
• items, minItems, maxItems: Voor array-validatie
• properties: Definieert regels voor velden binnen een object
• additionalProperties: Bepaalt of extra (ongedefinieerde) velden zijn toegestaan

MongoDB laat bewust enkele geavanceerde features uit de volledige JSON Schema weg, zoals:

• Schema-referenties ($ref).
• Conditionele logica (if/then/else).
• Compositie-operatoren (oneOf, allOf, anyOf).

Voor de volledige lijst met ondersteunde opties, bekijk de officiële MongoDB $jsonSchema-documentatie.

In dit artikel focussen we op de meest praktische en breed ondersteunde keywords—genoeg om veelvoorkomende validatiebehoeften in de praktijk te dekken zonder overdreven complexiteit.

Voor een breder begrip van hoe MongoDB past in het NoSQL-landschap, bekijk deze uitgebreide tutorial.

Een collectie maken met basisvalidatie

Nu we de structuur van een movies-document hebben gezien, maken we een nieuwe collectie die enkele basisregels afdwingt met $jsonSchema. We beginnen met een paar veelvoorkomende beperkingen:

• title: moet een string zijn en is verplicht
• year: moet een integer zijn en is verplicht
• genres: moet een array van strings zijn
• runtime: moet een positief geheel getal zijn

We noemen deze nieuwe collectie validated_movies.

De collectie aanmaken

Voer de volgende opdracht uit om de collectie met validatie te maken:

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"
});Mogelijk gemaakt door

Een geldig document invoegen

Laten we nu een document invoegen dat aan het schema voldoet:

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

✅ Dit zou moeten slagen.

Een ongeldig document invoegen

Probeer een document in te voegen waarin het veld title ontbreekt:

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

❌ Dit mislukt met een validatiefout omdat title vereist is.

Figuur 2. De eerste opdracht voegt een geldig filmdocument in de collectie validated_movies in, met alle verplichte velden en datatypes. De tweede opdracht probeert een document zonder het vereiste title-veld in te voegen, wat leidt tot een validatiefout.

Werken met bestaande collecties

Je hoeft niet vanaf nul te beginnen om schema-validatie te gebruiken. MongoDB laat je validatieregels toepassen op bestaande collecties met het commando collMod. Dit is vooral handig als je structuur wilt toevoegen aan een legacy-dataset zonder bestaande documenten te beïnvloeden.

In deze sectie passen we een validator toe op de collectie movies uit de database sample_mflix.

Een validator toevoegen met collMod

Laten we een basisregel afdwingen: elk moviedocument moet een veld title van het type string hebben.

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"
});Mogelijk gemaakt door

Validatieregels van de collectie bekijken

Na het aanpassen van de collectie movies met het commando collMod wil je misschien bevestigen welke validatieregels momenteel actief zijn.

Om de huidige schema-validator te controleren, voer je uit:

db.getCollectionInfos({ name: "movies" })[0].options.validatorMogelijk gemaakt door

Dit retourneert het $jsonSchema-object dat de validatieregels op de collectie definieert. Het is een handige manier om te verifiëren dat je configuratie correct is toegepast, vooral na het wisselen van modi zoals warn naar error, of bij het updaten van de structuur van verplichte velden.

Uitleg van validationLevel en validationAction

• validationLevel: "moderate": Valideert alleen documenten die worden ingevoegd of bijgewerkt. Bestaande documenten die niet aan het schema voldoen, veroorzaken geen fouten.

• validationAction: "warn": In plaats van ongeldige writes te weigeren, logt MongoDB een waarschuwing. Dit is handig in productie als je schema-overtredingen wilt monitoren voordat je ze afdwingt.

Probeer een document in te voegen dat het schema schendt:

db.movies.insertOne({
  year: 2023
});Mogelijk gemaakt door

Je ziet een waarschuwing in de logs, maar de write slaagt. Je kunt de actie later wijzigen in "error" om de regel strikt af te dwingen zodra je zeker bent.

Figuur 3. De opdracht insertOne() voegt met succes een document toe dat de schemaregel schendt, omdat de validatieactie is ingesteld op "warn." MongoDB accepteert de write, maar het ontbrekende title-veld zou een validatiefout hebben veroorzaakt als "error" was afgedwongen.

Geneste documenten en arrays valideren

MongoDB-documenten bevatten vaak geneste structuren, zoals objecten in objecten en arrays met waarden. Gelukkig ondersteunt $jsonSchema de validatie van beide. Laten we bekijken hoe je regels toepast op subdocumenten en array-inhoud met velden uit de collectie movies.

Een genest document valideren

In de collectie movies bevat elk document een embedded object imdb met velden zoals rating, votes en id. Laten we een regel afdwingen die zorgt dat:

• imdb een object is (indien aanwezig).
• imdb.rating een getal tussen 0 en 10 is.

Zo definieer je dat:

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"
            }
          }
        }
      }
    }
  }
});Mogelijk gemaakt door

Het geneste document testen

✅ Geldige insert:

db.validated_nested.insertOne({
  title: "Interstellar",
  imdb: { rating: 8.6 }
});Mogelijk gemaakt door

❌ Ongeldige insert (rating buiten bereik):

db.validated_nested.insertOne({
  title: "Bad Movie",
  imdb: { rating: 12.5 }
});Mogelijk gemaakt door

Dit levert een validatiefout op omdat de rating groter is dan 10.      Figuur 4. Deze insert-operatie mislukt omdat het veld rating binnen het geneste imdb-object de maximaal toegestane waarde 10 overschrijdt, zoals gedefinieerd in het schema. MongoDB geeft een validatiefout vanwege de schending van de $jsonSchema-regel.

Arrays valideren

Je kunt ook beperkingen voor arrays afdwingen. Stel dat je wilt garanderen dat:

• genres een array van strings is.
• De array minstens één item bevat.

Voeg dit toe aan je schema:

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

Meerdere beperkingen combineren

In realistische toepassingen moeten je documenten vaak aan meerdere validatieregels tegelijk voldoen—voor verplichte velden, toegestane waarden, types en geneste structuren. Met $jsonSchema combineer je eenvoudig meerdere beperkingen in één schemadefinitie.

Laten we een vollediger voorbeeld maken op basis van de structuur van het movies-document. We dwingen de volgende regels af:

• title: verplicht, moet een string zijn
• year: verplicht, integer, ≥ 1888
• rated: optioneel, maar moet overeenkomen met een vooraf gedefinieerde set waarden
• genres: moet een niet-lege array van strings zijn
• imdb.rating: getal tussen 0 en 10
• tomatoes.viewer.rating: optioneel, getal tussen 0 en 5

Een gevalideerde collectie maken

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"
                }
              }
            }
          }
        }
      }
    }
  }
});Mogelijk gemaakt door

Een geldig document invoegen: 

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

Een ongeldig document invoegen:

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

Dit mislukt vanwege:

• Ongeldige waarde voor rated.
• Lege array genres.
• imdb.rating groter dan 10.
• tomatoes.viewer.rating groter dan 5.

Figuur 5. Deze insert-operatie mislukt vanwege meerdere schema-overtredingen in de collectie validated_full. Het veld rated bevat een waarde die niet is toegestaan door de enum, genres is een lege array en schendt de regel minItems, imdb.rating overschrijdt het maximum van 10 en heeft het verkeerde type, en tomatoes.viewer.rating overschrijdt het toegestane maximum van 5. MongoDB weigert de insert met een gedetailleerde validatiefout.

Validatieniveaus en -acties uitgelegd

MongoDB geeft je fijne controle over hoe en wanneer schema-validatie wordt toegepast. Bij het definiëren van validatieregels bepalen twee opties het gedrag van je database:

• validationLevel: Wanneer de regel moet worden afgedwongen
• validationAction: Wat er gebeurt als een document niet aan de regel voldoet

validationLevel

Deze optie bepaalt welke operaties aan schema-validatie onderhevig zijn.

• strict: Alle inserts en updates moeten aan het schema voldoen. Dit is de standaard en veiligste modus.
• moderate: Alleen documenten die worden ingevoegd of bijgewerkt worden gevalideerd. Bestaande documenten, zelfs als ze ongeldig zijn, blijven ongemoeid.

Wanneer te gebruiken:

• Gebruik strict voor nieuwe collecties waarin je het schema vanaf het begin volledig wilt afdwingen.
• Gebruik moderate bij het toepassen van validatie op collecties die al legacy- of ongestructureerde data bevatten.

validationAction

Deze optie bepaalt hoe MongoDB reageert wanneer een document de validatieregels schendt.

• error: De write-operatie wordt geweigerd en er wordt een validatiefout geretourneerd.
• warn: De write wordt geaccepteerd, maar er wordt intern een waarschuwing gelogd door de server.

Belangrijk: Op MongoDB Atlas zijn waarschuwingen van warn niet zichtbaar voor gebruikers—je ziet ze niet in de UI of standaardlogs.

Wanneer te gebruiken:

• Gebruik warn in development of tijdens een gefaseerde uitrol om overtredingen te monitoren zonder writes te blokkeren.
• Schakel over naar error wanneer je zeker weet dat je applicatie geldige documenten schrijft en je het schema strikt wilt afdwingen.

Voorbeeld: overschakelen van Warn naar Error

Stel, je begon hiermee:

db.runCommand({
  collMod: "validated_full",
  validationAction: "warn",
  validationLevel: "moderate"
});Mogelijk gemaakt door

Na het observeren van het gedrag van je applicatie kun je overschakelen naar strikte handhaving:

db.runCommand({
  collMod: "validated_full",
  validationAction: "error",
  validationLevel: "strict"
});Mogelijk gemaakt door

Figuur 6. Twee collMod-opdrachten worden gebruikt om het validatiegedrag van de collectie validated_full te wijzigen. De eerste zet validationAction op "warn" en validationLevel op "moderate," zodat ongeldige documenten kunnen worden ingevoegd terwijl interne waarschuwingen worden gelogd. De tweede opdracht schakelt over naar strikte handhaving door validationAction op "error" en validationLevel op "strict" te zetten, zodat alle inserts en updates volledig aan het gedefinieerde schema moeten voldoen.

Nu wordt elke ongeldige insert of update geblokkeerd met een foutmelding.

Veelvoorkomende valkuilen en tips voor debuggen

Bij schema-validatie kunnen kleine foutjes leiden tot verwarrende fouten—of erger, documenten die stilletjes aan je regels ontsnappen. Hier zijn enkele veelvoorkomende issues en hoe je ze voorkomt:

Verkeerde bsonType-waarden

Een van de meest voorkomende fouten bij het gebruik van $jsonSchema is JSON-types verwarren met MongoDB’s “bsonType”. Hoewel "string" en "array" duidelijk zijn, kunnen andere zoals getallen en booleans tricky zijn.

Bijvoorbeeld:

• Gebruik "int" of "long" voor gehele getallen.
• Gebruik "double" voor kommagetallen.
• Gebruik "bool" (niet "boolean") voor true/false-waarden.
• Gebruik "object" voor subdocumenten (niet "dict" of "map").
• Gebruik "array" voor lijsten.

Weet je niet zeker als welk type een veld is opgeslagen, inspecteer dan een document met typeof in de Mongo-shell of bekijk de data in MongoDB Compass.

Ontbrekende verplichte velden bij partiële updates

Bij gebruik van $set controleert de validatie alleen de velden die worden aangepast. Als je een volledige schemacontrole verwacht, zorg dan dat je een volledige documentvervanging doet of gebruik validationLevel: "strict" met applicatielogica die de volledige structuur afdwingt.

Lege arrays die toch slagen

Als je minItems niet opgeeft, slaagt een lege array:

	genres: {
	  bsonType: "array",
	  items: { bsonType: "string" }
	}
	// Accepts empty arrays by defaultMogelijk gemaakt door

Gebruik minItems: 1 om te garanderen dat er minstens één waarde aanwezig is.

Geen foutmelding in warn-modus

Zoals eerder besproken, blokkeert validationAction: "warn" geen writes en toont geen fouten in MongoDB Atlas. Het wordt alleen intern gelogd, waardoor validatie kan lijken “niet te werken”.

Gebruik tijdens ontwikkeling of in testomgevingen de modus "error" om problemen vroeg te onderscheppen.

Geneste veldpaden worden niet gecontroleerd als het ouderobject ontbreekt

Als imdb.rating vereist is, maar imdb geheel ontbreekt, controleert MongoDB het veld rating niet.

Om validatie op geneste velden af te dwingen, zorg je dat hun ouderobject óf vereist is óf bsonType: "object" heeft.

Documenten opvragen of updaten die niet aan het schema voldoen

Na het toepassen van validatie op een bestaande collectie is het vaak handig om documenten te identificeren die niet aan het nieuwe schema voldoen. Dat kan met de operator $jsonSchema in een query met $nor of $not.

Voorbeeld: ongeldige documenten vinden in de collectie movies

Stel dat je schema een title van het type "string" vereist. Om documenten te vinden die niet voldoen, kun je dit uitvoeren:

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

Dit retourneert documenten waarin title ontbreekt of een verkeerde type heeft.

Figuur 7. Deze query gebruikt $nor met $jsonSchema om documenten te vinden in de collectie movies die geen title-veld van het type string hebben. Het resultaat toont een document met _id: 683ce0050bd195c35e417534 dat alleen het veld year bevat, wat bevestigt dat het het schema met een vereiste title schendt. Deze techniek is handig om ongeldige documenten te identificeren voordat je strengere validatieregels afdwingt.

Je kunt deze aanpak ook gebruiken om:

• Legacy-documenten te auditen voordat je overschakelt van "warn" naar "error".
• Ongeldige documenten programmatisch op te schonen of te repareren.
• Rapporten over schema-naleving te genereren.

Afronding: schone data zonder flexibiliteit op te offeren

Het schemaloze ontwerp van MongoDB is een van zijn grootste krachten, maar dat betekent niet dat je je data ongecontroleerd moet laten. Met $jsonSchema definieer je krachtige validatieregels die structuur afdwingen terwijl je de flexibiliteit van MongoDB benut.

In dit artikel heb je geleerd hoe je:

• Collecties met validatieregels maakt.
• Beperkingen toepast op nieuwe en bestaande collecties.
• Geneste validatie gebruikt voor objecten en arrays.
• Validatiemodi en -acties configureert.
• Je schema’s met vertrouwen debugt en verfijnt.

Of je nu een greenfield-app bouwt of structuur toevoegt aan een legacy-systeem, schema-validatie geeft je de tools om je data te beschermen zonder de ontwikkeling te vertragen.

Volgende stappen en bronnen

Verder de diepte in? Bekijk deze bronnen:

• MongoDB Schema Validation-docs 
• MongoDB JSON Schema-docs
• Voorbeelddata op MongoDB Atlas

Bereid je je voor op sollicitaties? Deze topvragen over MongoDB testen je begrip van onderwerpen zoals schema-validatie en meer. Wil je je skills valideren? Deze certificeringsgids zet alles op een rij wat je moet weten om gecertificeerd te worden in MongoDB.

Onthoud: begin klein, test met "warn" en schakel over naar "error" zodra je zeker bent—je toekomstige zelf (en je data) zal je dankbaar zijn.