Validation du schéma MongoDB : Guide pratique avec exemples

MongoDB n'utilise pas de schéma, mais cela ne signifie pas pour autant que vos données doivent être désorganisées.

Dans cet article, vous apprendrez tout, des bases de la validation de schéma aux cas d'utilisation avancés à l'aide de l'opérateur $jsonSchema. Vous découvrirez comment rendre obligatoires certains champs, restreindre les types de données, appliquer des modèles et valider des documents imbriqués. 

Nous aborderons également le fonctionnement de la validation lors des insertions et des mises à jour, la modification des collections existantes, ainsi que les cas dans lesquels il convient d'utiliser différents niveaux et actions de validation. 

À la fin de cette formation, vous serez en mesure d'appliquer la validation de schéma à vos collections MongoDB, garantissant ainsi la propreté et la prévisibilité de vos données, sans renoncer à la flexibilité qui fait la réputation de MongoDB.

Pourquoi la validation de schéma est-elle importante dans MongoDB ?

Le modèle de document dynamique de MongoDB offre rapidité et flexibilité en permettant aux documents d'une même collection d'avoir des champs ou des structures différents. Il s'agit d'un avantage considérable lors des premières phases de développement ou lors d'itérations rapides. Cependant, cette même flexibilité peut rapidement devenir un inconvénient, entraînant des données incohérentes, incomplètes ou invalides à mesure que votre application se développe.

C'est là qu'intervientla validation de schéma. Il vous permet de définir des règles pour vos documents, telles que les champs obligatoires, les types de données spécifiques ou les structures imbriquées, tout en conservant la flexibilité de MongoDB.

Dans cet article, vous apprendrez à utiliser le puissant opérateur d'$jsonSchema de MongoDB pour appliquer ces règles à vos collections. Que vous souhaitiez éviter les insertions incorrectes dans une nouvelle application ou mettre à niveau les règles de validation d'une base de données existante, la validation de schéma vous aide à garantir la propreté de vos données, la prévisibilité de vos requêtes et la stabilité de votre application.

Si vous débutez avec MongoDB et Python, ce cours d'introduction à MongoDB est un excellent moyen de vous familiariser avec les requêtes et les intégrations avant de vous lancer dans la validation de schémas.

Avant de commencer

Pour tirer le meilleur parti de ce guide, vous devez disposer d'un accès à un cluster MongoDB Atlas. La version gratuite est largement suffisante pour suivre le cours.

Afin de rendre les concepts aussi clairs et applicables que possible, nous utiliserons un exemple de jeu de données MongoDB Atlas,plus précisément, la base de données sample_mflix. Cet ensemble de données comprend des collections telles que des films, des commentaires, des utilisateurs et des cinémas, auxquelles nous ferons référence tout au long de l'article pour illustrer chaque exemple. L'ensemble de données comprend des documents contenant des champs tels que des objets imbriqués, des tableaux, des chaînes de caractères, des nombres et des champs facultatifs.

Chargez l'ensemble de données échantillon (si nécessaire).

1. Accédez à votre tableau de bord MongoDB Atlas.

2. Sélectionnez votre cluster, cliquez sur le bouton « ... » et sélectionnez « Charger un exemple de jeu de données ».

3. Veuillez patienter quelques minutes jusqu'à ce que la base de données sample_mflix soit disponible.

Premiers pas avec la validation de schéma

Une fois votre ensemble de données chargé, connectez-vous à votre cluster à l'aide de MongoDB Shell (mongosh) ou MongoDB Compass, puis passez à l'ensemble de données :

use sample_mflix

Exploration de l'ensemble de données avec findOne()

Vérifions l'un des documents de la collection de films :

db.movies.findOne()

Voici une version simplifiée de ce que vous pourriez voir :

Figure 1. Cette requête utilise findOne() pour récupérer un seul document échantillon à partir de la collection movies dans la base de données sample_mflix. Le résultat affiche divers champs, notamment le titre, l'année, les genres et les objets imbriqués tels que imdb et tomatoes.viewer.

Ce document contient un mélange de valeurs scalaires, de tableaux et d'objets imbriqués, ce qui le rend idéal pour illustrer diverses techniques de validation. Dans la section suivante, nous allons créer une nouvelle collection basée sur cette structure et définir notre premier schéma de validation à l'aide d' $jsonSchema.

Mots-clés, extensions et restrictions pris en charge

La validation de l'$jsonSchema de MongoDB est basée sur la spécification JSON Schema Draft 4, avec quelques modifications et omissions. Bien que toutes les fonctionnalités de la spécification d'origine ne soient pas prises en charge, MongoDB inclut un sous-ensemble ciblé et pratique adapté à la validation des documents BSON.

Voici quelques-uns des mots-clés les plus couramment utilisés :

• bsonType: Mot-clé de type spécifique à MongoDB (par exemple « string », « int », « array », « object »)
• s requises: Indique les champs obligatoires.
• minimale/maximale: Pour la validation d'une plage numérique
• s sur le modèle: Pour la validation du format des chaînes à l'aide d'expressions régulières
• énumération: Limite un champ à un ensemble de valeurs autorisées.
• items, minItems, maxItems: Pour la validation des tableaux
• s des propriétés: Définit les règles pour les champs à l'intérieur d'un objet.
• propriétés supplémentaires: Contrôle si des champs supplémentaires (non définis) sont autorisés.

MongoDB omet intentionnellement certaines fonctionnalités avancées du schéma JSON complet, telles que :

• Références de schéma ($ref).
• Logique conditionnelle (si/alors/sinon).
• Opérateurs de composition (oneOf, allOf, anyOf).

Pour obtenir la liste complète des options prises en charge, veuillez consulter la documentation officielle MongoDB $jsonSchema.

Dans cet article, nous nous concentrerons sur les mots-clés les plus pratiques et les plus largement pris en charge, suffisants pour couvrir les besoins courants en matière de validation dans le monde réel sans complexité excessive.

Pour mieux comprendre comment MongoDB s'intègre dans le paysage NoSQL, veuillez consulter ce tutoriel complet.

Création d'une collection avec validation de base

Maintenant que nous avons vu la structure d'un document movies, créons une nouvelle collection qui applique certaines règles de base à l'aide d'$jsonSchema. Commençons par quelques contraintes courantes :

• titre: doit être une chaîne de caractères et est obligatoire
• année: doit être un nombre entier et est obligatoire
• genres: doit être un tableau de chaînes de caractères
• durée d'exécution: doit être un nombre entier positif

Nous appellerons cette nouvelle collection « validated_movies ».

Création de la collection

Exécutez la commande suivante pour créer la collection avec validation :

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

Insérer un document valide

Maintenant, insérons un document qui respecte le schéma :

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

✅ Cela devrait fonctionner.

Insertion d'un document non valide

Veuillez essayer d'insérer un document dans lequel le champ « title » est manquant :

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

Cela échouera avec une erreur de validation car le champ « title » est obligatoire.

Figure 2. La première commande insère un document vidéo valide dans la collection validated_movies, en transmettant tous les champs et types de données requis. La deuxième commande tente d'insérer un document sans le champ de titre requis, ce qui entraîne une erreur de validation.

Utilisation des collections existantes

Il n'est pas nécessaire de repartir de zéro pour utiliser la validation de schéma. MongoDB vous permet d'appliquer des règles de validation aux collections existantes à l'aide de la commande « collMod ». Cette fonctionnalité est particulièrement utile lorsque vous souhaitez structurer un ensemble de données existant sans affecter les documents existants.

Dans cette section, nous allons appliquer un validateur à la collection de films de la base de données sample_mflix.

Ajouter un validateur avec collMod

Appliquons une règle fondamentale : Chaque document de film doit comporter un champ « title » de type chaîne de caractères.

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

Vérification des règles de validation sur la collection

Après avoir modifié la collection d'movies s à l'aide de la commande « collMod », vous souhaiterez peut-être vérifier quelles règles de validation sont actuellement actives.

Pour vérifier le validateur de schéma actuel, veuillez exécuter :

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

Cette méthode renvoie l'objet d'$jsonSchema qui définit les règles de validation sur la collection. Il s'agit d'un moyen pratique de vérifier que votre configuration a été appliquée correctement, en particulier après avoir changé de mode (par exemple, de « warn » à « error ») ou mis à jour la structure des champs obligatoires.

Comprendre validationLevel et validationAction

• validationLevel : « moderate »: Valide uniquement les documents en cours d'insertion ou de mise à jour. Les documents existants qui ne correspondent pas au schéma ne déclencheront pas d'erreurs.

• validationAction : « warn »: Au lieu de rejeter les écritures non valides, MongoDB enregistre un avertissement. Ceci est utile en production lorsque vous souhaitez surveiller les violations de schéma avant de les appliquer.

Veuillez essayer d'insérer un document qui enfreint le schéma :

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

Un avertissement s'affichera dans les journaux, mais l'écriture sera effectuée. Vous pouvez modifier l'action ultérieurement et la remplacer par « erreur » afin d'appliquer strictement la règle une fois que vous êtes certain de son efficacité.

Figure 3. La commande insertOne() ajoute correctement un document qui enfreint la règle du schéma, car l'action de validation est définie sur « warn ». MongoDB accepte l'écriture, mais le champ titre manquant aurait déclenché une erreur de validation si « error » avait été appliqué.

Validation de documents imbriqués et de tableaux

Les documents MongoDB contiennent souvent des structures imbriquées, telles que des objets à l'intérieur d'autres objets et des tableaux de valeurs. Heureusement, $jsonSchema prend en charge la validation des deux formats. Explorons comment appliquer des règles à des sous-documents et au contenu d'un tableau à l'aide des champs de la collection movies.

Validation d'un document imbriqué

Dans la collection « films », chaque document comprend un objet intégré « imdb » avec des champs tels que « rating », « votes » et « id ». Mettons en place une règle qui garantit :

• imdb est un objet (s'il est présent).
• imdb.rating est un nombre compris entre 0 et 10.

Voici comment définir cela :

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

Test du document imbriqué

Insertion valide :

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

Insertion non valide (note hors limites) :

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

Cela entraînera une erreur de validation, car la note est supérieure à 10.      Figure 4. Cette opération d'insertion échoue car le champ rating à l'intérieur de l'objet imbriqué imdb dépasse la valeur maximale autorisée de 10, telle que définie dans le schéma. MongoDB renvoie une erreur de validation en raison de la violation de la règle $jsonSchema.

Validation des tableaux

Vous pouvez également appliquer des contraintes de tableau. Supposons que vous souhaitiez vous assurer que :

• genres est un tableau de chaînes de caractères.
• Le tableau doit contenir au moins un élément.

Ajoutez ceci à votre schéma :

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

Combiner plusieurs contraintes

Dans les applications réelles, vos documents doivent souvent satisfaire plusieurs règles de validation à la fois, notamment les champs obligatoires, les valeurs autorisées, les types et les structures imbriquées. Grâce à l' $jsonSchema, vous pouvez facilement combiner plusieurs contraintes dans une seule définition de schéma.

Construisons un exemple plus complet en utilisant la structure du document « movies ». Nous appliquerons les règles suivantes :

• titre: obligatoire, doit être une chaîne de caractères
• année: obligatoire, nombre entier, ≥ 1888
• évalué: facultatif, mais doit correspondre à un ensemble de valeurs prédéfinies
• genres: doit être un tableau non vide de chaînes de caractères
• imdb.rating: nombre compris entre 0 et 10
• tomatoes.viewer.rating: facultatif, nombre compris entre 0 et 5

Création d'une collection validée

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

Insertion d'un document valide : 

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

Insertion d'un document non valide :

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

Cela échouera pour les raisons suivantes :

• Valeur d'rated e non valide.
• Vider le tableau d'genres.
• imdb.rating supérieur à 10.
• tomatoes.viewer.rating supérieur à 5.

Figure 5. Cette opération d'insertion échoue en raison de plusieurs violations de schéma dans la collection validated_full. Le champ « rated » contient une valeur non autorisée par l'énumération, « genres » est un tableau vide qui enfreint la règle « minItems », « imdb.rating » dépasse la valeur maximale de 10 et est de type incorrect, et « tomatoes.viewer.rating » dépasse la valeur maximale autorisée de 5. MongoDB rejette l'insertion avec une erreur de validation détaillée.

Niveaux de validation et actions expliqués

MongoDB vous offre un contrôle précis sur la manière et le moment où la validation du schéma est appliquée. Lors de la définition des règles de validation, deux options influencent le comportement de votre base de données :

• niveau de validation: Quand la règle doit-elle être appliquée ?
• validationAction: Que se passe-t-il lorsqu'un document ne respecte pas la règle ?

validationLevel

Cette option contrôle les opérations soumises à la validation du schéma.

• strict: Toutes les insertions et mises à jour doivent être conformes au schéma. Il s'agit du mode par défaut et le plus sécurisé.
• modéré: Seuls les documents qui sont insérés ou mis à jour sont validés. Les documents existants, même s'ils ne sont plus valides, ne sont pas modifiés.

Quand utiliser :

• Utilisez strict pour les nouvelles collections où vous souhaitez appliquer intégralement le schéma dès le début.
• Veuillez utiliser la validation avec modération lorsque vous l'appliquez à des collections contenant déjà des données héritées ou non structurées.

validationAction

Cette option contrôle la manière dont MongoDB réagit lorsqu'un document enfreint les règles de validation.

• erreur: L'opération d'écriture est rejetée et une erreur de validation est renvoyée.
• avertir: L'écriture est acceptée, mais un avertissement est enregistré en interne par le serveur.

Important : Sur MongoDB Atlas, les avertissements générés par warn ne sont pas visibles par les utilisateurs. Vous ne les verrez ni dans l'interface utilisateur, ni dans les journaux standard.

Quand utiliser :

• Utilisez « warn » pendant le développement ou lors d'un déploiement progressif pour surveiller les violations sans bloquer les écritures.
• Passez à l'erreur lorsque vous êtes certain que votre application écrit des documents valides et que vous souhaitez appliquer strictement le schéma.

Exemple : Passage de « Avertissement » à « Erreur »

Supposons que vous ayez commencé par ceci :

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

Après avoir observé le comportement de votre application, vous pouvez passer à une application stricte :

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

Figure 6. Deux commandes collMod sont utilisées pour modifier le comportement de validation de la collection validated_full. Le premier définit validationAction sur « warn » et validationLevel sur « moderate », ce qui permet d'insérer des documents non valides tout en enregistrant des avertissements internes. La deuxième commande passe à une application stricte en définissant validationAction sur « error » et validationLevel sur « strict », garantissant ainsi que toutes les insertions et mises à jour doivent être entièrement conformes au schéma défini.

Désormais, toute insertion ou mise à jour non valide sera bloquée et accompagnée d'un message d'erreur.

Pièges courants et conseils de dépannage

Lors de la validation de schémas, de petites erreurs peuvent entraîner des erreurs déroutantes, voire pire, des documents contournant vos règles sans que vous vous en rendiez compte. Voici quelques-uns des problèmes les plus fréquents et comment les éviter :

Valeurs bsonType incorrectes

L'une des erreurs les plus courantes lors de l'utilisation d'$jsonSchema, consiste à confondre les types JSON avec le « bsonType » de MongoDB. Si les types « chaîne » et « tableau » sont simples, d'autres types tels que les nombres et les booléens peuvent s'avérer plus complexes.

Par exemple :

• Veuillez utiliser « int » ou « long » pour les nombres entiers.
• Veuillez utiliser « double » pour les nombres à virgule flottante.
• Veuillez utiliser « bool » (et non « boolean ») pour les valeurs vrai/faux.
• Veuillez utiliser « object » pour les sous-documents (et non « dict » ou « map »).
• Veuillez utiliser « array » pour les listes.

Si vous n'êtes pas certain du type de stockage d'un champ, vous pouvez inspecter un document à l'aide de typeof dans le shell Mongo ou examiner les données à l'aide de MongoDB Compass.

Champs obligatoires manquants dans les mises à jour partielles

Lorsque vous utilisez l'$set, la validation vérifie uniquement les champs modifiés. Si vous souhaitez effectuer une vérification complète du schéma, assurez-vous de remplacer l'intégralité du document ou d'utiliser l'option « validationLevel: "strict" » avec une logique d'application imposant une structure complète.

Les tableaux vides sont transmis alors qu'ils ne devraient pas l'être

Si vous oubliez de spécifier minItems, un tableau vide sera transmis :

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

Veuillez utiliser « minItems: 1 » pour vous assurer qu'au moins une valeur est présente.

Aucune erreur en mode avertissement

Comme indiqué précédemment, l'validationAction: "warn" ne bloque pas les écritures ni les erreurs de surface dans MongoDB Atlas. Il n'enregistre que des informations en interne, donc la validation peut sembler « ne pas fonctionner ».

Veuillez utiliser le mode « erreur » pendant le développement ou les environnements de test afin de détecter rapidement les problèmes.

Les chemins de champs imbriqués ne sont pas vérifiés si l'objet parent est manquant.

Si imdb.rating est requis, mais que imdb est totalement absent, MongoDB ne vérifiera pas rating.

Pour appliquer la validation sur les champs imbriqués, veuillez vous assurer que leur objet parent est obligatoire ou qu'il dispose d'bsonType: "object".

Requête ou mise à jour de documents non conformes au schéma

Après avoir appliqué la validation à une collection existante, il est souvent utile d'identifier les documents qui ne sont pas conformes au nouveau schéma. Vous pouvez le faire en utilisant l'opérateur $jsonSchema dans une requête avec $nor ou $not.

Exemple : Veuillez identifier les documents non valides dans la collection de films.

Supposons que votre schéma requiert un titre de type « string ». Pour rechercher des documents qui ne correspondent pas, vous pouvez exécuter :

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

Cela renverra les documents qui n'ont pas de titre ou dont le titre est incorrect.

Figure 7. Cette requête utilise $nor avec $jsonSchema pour rechercher dans la collection movies les documents qui ne possèdent pas de champ title de type chaîne. Le résultat affiche un document avec _id : 683ce0050bd195c35e417534 qui ne contient que le champ année, confirmant qu'il ne respecte pas le schéma exigeant un titre. Cette technique est utile pour identifier les documents non valides avant d'appliquer des règles de validation plus strictes.

Vous pouvez également utiliser cette approche pour :

• Vérifiez les documents hérités avant de passer de « avertissement » à « erreur ».
• Nettoyez ou corrigez les documents non valides de manière programmée.
• Générer des rapports sur la conformité des schémas.

Conclusion : Nettoyez vos données sans sacrifier la flexibilité

La conception sans schéma de MongoDB est l'un de ses principaux atouts, mais cela ne signifie pas pour autant que vous devez laisser vos données sans surveillance. Avec l' $jsonSchema, vous pouvez définir des règles de validation puissantes qui imposent une structure tout en tirant parti de la flexibilité de MongoDB.

Tout au long de cet article, vous avez appris à :

• Créez des collections avec des règles de validation.
• Appliquez des contraintes aux collections existantes et à celles que vous créez.
• Veuillez utiliser la validation imbriquée pour les objets et les tableaux.
• Configurez les modes et les actions de validation.
• Déboguez et affinez vos schémas en toute confiance.

Que vous développiez une nouvelle application ou ajoutiez une structure à un système existant, la validation de schéma vous fournit les outils nécessaires pour protéger vos données sans ralentir le développement.

Prochaines étapes et ressources

Souhaitez-vous approfondir vos connaissances ? Veuillez consulter les ressources suivantes :

• Documentation relative à la validation de schéma MongoDB 
• Documentation sur le schéma JSON MongoDB
• Exemple de données sur MongoDB Atlas

Vous vous préparez pour des entretiens ? C es questions fréquentes sur MongoDB évalueront votre maîtrise de sujets tels que la validation de schémas et bien plus encore. Vous souhaitez valider vos compétences en matière d'? Ce guide de certification décrittout ce que vous devez savoir pour obtenir la certification MongoDB.

N'oubliez pas : commencez modestement, testez avec « avertir », puis passez à « erreur » une fois que vous êtes sûr de vous. Votre futur vous (et vos données) vous en remercieront.