Convalida dello schema in MongoDB: guida pratica con esempi

MongoDB può essere senza schema, ma questo non significa che i tuoi dati debbano essere disordinati.

In questo articolo imparerai tutto, dalle basi della convalida dello schema ai casi d’uso avanzati con l’operatore $jsonSchema. Vedrai come imporre campi obbligatori, limitare i tipi di dato, applicare pattern e convalidare documenti annidati. 

Copriamo anche come funziona la convalida durante insert e update, come modificare collezioni esistenti e quando usare diversi livelli e azioni di convalida. 

Alla fine, saprai applicare con sicurezza la convalida dello schema alle tue collezioni MongoDB, mantenendo i dati puliti e prevedibili senza rinunciare alla flessibilità per cui MongoDB è noto. Puoi anche dare un’occhiata al nostro video sulla convalida dello schema per saperne di più.

Perché la convalida dello schema è importante in MongoDB

Il modello di documenti dinamici di MongoDB offre velocità e flessibilità permettendo a documenti nella stessa collezione di avere campi o strutture diverse. È un grande vantaggio nelle fasi iniziali di sviluppo o durante iterazioni rapide. Tuttavia, la stessa flessibilità può diventare presto un problema, causando dati incoerenti, incompleti o non validi man mano che l’applicazione cresce.

Qui entra in gioco la convalida dello schema. Ti permette di definire regole per i tuoi documenti — come campi obbligatori, tipi di dato specifici o strutture annidate — abbracciando comunque la natura flessibile di MongoDB.

In questo articolo vedrai come usare il potente operatore $jsonSchema di MongoDB per applicare queste regole alle tue collezioni. Che tu stia prevenendo insert malformati in una nuova applicazione o aggiungendo regole di convalida a un database legacy, la convalida dello schema aiuta a garantire che i dati restino puliti, le query prevedibili e l’applicazione stabile.

Se sei alle prime armi con MongoDB e Python, questo corso introduttivo su MongoDB è un ottimo modo per fare pratica con query e integrazioni prima di approfondire la convalida dello schema.

Prima di iniziare

Per sfruttare al meglio questa guida, ti servirà l’accesso a un cluster MongoDB Atlas. Il piano gratuito è più che sufficiente per seguire.

Per rendere i concetti il più chiari e applicabili possibile, utilizzeremo un dataset di esempio di MongoDB Atlas — in particolare il database sample_mflix. Questo dataset include collezioni come movies, comments, users e theaters, che citeremo per tutto l’articolo per illustrare ciascun esempio. Il dataset include documenti con campi come oggetti annidati, array, stringhe, numeri e campi opzionali.

Carica il dataset di esempio (se serve)

1. Vai alla dashboard di MongoDB Atlas.

2. Scegli il tuo cluster, clicca sul pulsante “…” e seleziona Load Sample Dataset.

3. Attendi qualche minuto finché il database sample_mflix non diventa disponibile.

Primi passi con la convalida dello schema

Una volta caricato il dataset, connettiti al cluster usando MongoDB Shell (mongosh) o MongoDB Compass, poi passa al dataset:

use sample_mflixOfferto da

Esplorare il dataset con findOne()

Esploriamo uno dei documenti della collezione movies:

db.movies.findOne()Offerto da

Ecco una versione semplificata di ciò che potresti vedere:

Figura 1. Questa query usa findOne() per recuperare un singolo documento di esempio dalla collezione movies nel database sample_mflix. Il risultato mostra vari campi, tra cui title, year, genres e oggetti annidati come imdb e tomatoes.viewer.

Questo documento contiene un mix di valori scalari, array e oggetti annidati, ideale per dimostrare un’ampia gamma di tecniche di convalida. Nella prossima sezione, creeremo una nuova collezione basata su questa struttura e definiremo il nostro primo schema di convalida usando $jsonSchema.

Parole chiave supportate, estensioni e limitazioni

La convalida $jsonSchema di MongoDB si basa sulla specifica JSON Schema Draft 4, con alcune modifiche e omissioni. Anche se non sono supportate tutte le funzionalità della specifica originale, MongoDB include un sottoinsieme mirato e pratico adatto a convalidare documenti BSON.

Ecco alcune delle parole chiave più usate:

• bsonType: parola chiave di tipo specifica di MongoDB (ad es. "string", "int", "array", "object")
• required: specifica quali campi devono essere presenti
• minimum/maximum: per la convalida degli intervalli numerici
• pattern: per validare il formato delle stringhe con espressioni regolari
• enum: limita un campo a un insieme di valori consentiti
• items, minItems, maxItems: per la convalida degli array
• properties: definisce regole per i campi dentro un oggetto
• additionalProperties: controlla se sono consentiti campi extra (non definiti)

MongoDB omette intenzionalmente alcune funzionalità avanzate del JSON Schema completo, come:

• Riferimenti di schema ($ref).
• Logica condizionale (if/then/else).
• Operatori di composizione (oneOf, allOf, anyOf).

Per l’elenco completo delle opzioni supportate, consulta la documentazione ufficiale di MongoDB su $jsonSchema.

In questo articolo ci concentreremo sulle parole chiave più pratiche e largamente supportate, sufficienti a coprire le esigenze di convalida comuni senza complessità eccessiva.

Per una visione più ampia di come MongoDB si inserisce nel panorama NoSQL, esplora questo tutorial completo.

Creare una collezione con convalida di base

Ora che abbiamo visto la struttura di un documento movies, creiamo una nuova collezione che impone alcune regole di base usando $jsonSchema. Partiremo da alcuni vincoli comuni:

• title: deve essere una stringa ed è obbligatorio
• year: deve essere un intero ed è obbligatorio
• genres: deve essere un array di stringhe
• runtime: deve essere un intero positivo

Chiameremo questa nuova collezione validated_movies.

Creare la collezione

Esegui il seguente comando per creare la collezione con convalida:

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

Inserire un documento valido

Ora inseriamo un documento che rispetta lo schema:

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

✅ Questo dovrebbe riuscire.

Inserire un documento non valido

Prova a inserire un documento a cui manca il campo title:

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

❌ Questo fallirà con un errore di convalida perché title è obbligatorio.

Figura 2. Il primo comando inserisce un documento di film valido nella collezione validated_movies, rispettando tutti i campi obbligatori e i tipi di dato. Il secondo comando tenta di inserire un documento senza il campo obbligatorio title, generando un errore di convalida.

Lavorare con collezioni esistenti

Non devi partire da zero per usare la convalida dello schema. MongoDB ti permette di applicare regole di convalida a collezioni esistenti usando il comando collMod. Questo è particolarmente utile quando vuoi aggiungere struttura a un dataset legacy senza influire sui documenti esistenti.

In questa sezione applicheremo un validator alla collezione movies del database sample_mflix.

Aggiungere un validator con collMod

Imponiamo una regola di base: ogni documento movie deve avere un campo title di tipo stringa.

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

Ispezionare le regole di convalida sulla collezione

Dopo aver modificato la collezione movies usando il comando collMod, potresti voler confermare quali regole di convalida sono attualmente attive.

Per verificare lo schema validator corrente, esegui:

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

Questo restituisce l’oggetto $jsonSchema che definisce le regole di convalida sulla collezione. È un modo utile per verificare che la configurazione sia stata applicata correttamente, soprattutto dopo aver cambiato modalità come warn in error o aggiornato la struttura dei campi obbligatori.

Capire validationLevel e validationAction

• validationLevel: "moderate": convalida solo i documenti che vengono inseriti o aggiornati. I documenti esistenti che non corrispondono allo schema non genereranno errori.

• validationAction: "warn": invece di rifiutare le scritture non valide, MongoDB registra un avviso. È utile in produzione quando vuoi monitorare le violazioni dello schema prima di applicarle in modo restrittivo.

Prova a inserire un documento che viola lo schema:

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

Vedrai un avviso nei log, ma la scrittura andrà a buon fine. Potrai cambiare l’azione in "error" più tardi per imporre rigorosamente la regola quando sarai sicuro.

Figura 3. Il comando insertOne() aggiunge con successo un documento che viola la regola dello schema, perché l’azione di convalida è impostata su "warn." MongoDB accetta la scrittura, ma l’assenza del campo title avrebbe generato un errore di convalida se fosse stato applicato "error".

Convalidare documenti annidati e array

I documenti MongoDB includono spesso strutture annidate, come oggetti dentro oggetti e array di valori. Fortunatamente, $jsonSchema supporta la convalida di entrambi. Vediamo come applicare regole a sotto-documenti e contenuti degli array usando campi della collezione movies.

Convalidare un documento annidato

Nella collezione movies, ogni documento include un oggetto incorporato imdb con campi come rating, votes e id. Imponiamo una regola che garantisca che:

• imdb sia un oggetto (se presente).
• imdb.rating sia un numero tra 0 e 10.

Ecco come lo definiresti:

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

Testare il documento annidato

✅ Insert valido:

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

❌ Insert non valido (rating fuori range):

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

Questo genererà un errore di convalida perché il rating è maggiore di 10.      Figura 4. Questa operazione di insert fallisce perché il campo rating all’interno dell’oggetto annidato imdb supera il valore massimo consentito di 10, come definito nello schema. MongoDB genera un errore di convalida per la violazione della regola $jsonSchema.

Convalidare gli array

Puoi anche imporre vincoli sugli array. Poniamo di voler garantire che:

• genres sia un array di stringhe.
• L’array contenga almeno un elemento.

Aggiungi questo allo schema:

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

Combinare più vincoli

Nelle applicazioni reali, spesso i tuoi documenti devono soddisfare più regole di convalida contemporaneamente — coprendo campi obbligatori, valori consentiti, tipi e strutture annidate. Con $jsonSchema puoi combinare facilmente più vincoli in un’unica definizione di schema.

Costruiamo un esempio più completo usando la struttura del documento movies. Imporremo le seguenti regole:

• title: obbligatorio, deve essere una stringa
• year: obbligatorio, intero, ≥ 1888
• rated: opzionale, ma deve corrispondere a un insieme predefinito di valori
• genres: deve essere un array non vuoto di stringhe
• imdb.rating: numero tra 0 e 10
• tomatoes.viewer.rating: opzionale, numero tra 0 e 5

Creare una collezione con convalida completa

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

Inserire un documento valido: 

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

Inserire un documento non valido:

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

Questo fallirà a causa di:

• Valore rated non valido.
• Array genres vuoto.
• imdb.rating superiore a 10.
• tomatoes.viewer.rating superiore a 5.

Figura 5. Questa operazione di insert fallisce per più violazioni dello schema nella collezione validated_full. Il campo rated contiene un valore non consentito dall’enum, genres è un array vuoto che viola la regola minItems, imdb.rating supera il massimo di 10 e ha il tipo sbagliato, e tomatoes.viewer.rating supera il massimo consentito di 5. MongoDB rifiuta l’inserimento con un errore di convalida dettagliato.

Livelli e azioni di convalida spiegati

MongoDB ti offre un controllo granulare su come e quando viene applicata la convalida dello schema. Quando definisci le regole di convalida, due opzioni influenzano il comportamento del database:

• validationLevel: quando la regola deve essere applicata
• validationAction: cosa succede quando un documento non rispetta la regola

validationLevel

Questa opzione controlla quali operazioni sono soggette alla convalida dello schema.

• strict: tutte le insert e gli update devono essere conformi allo schema. È la modalità predefinita e più sicura.
• moderate: vengono convalidati solo i documenti inseriti o aggiornati. I documenti esistenti, anche se non validi, non vengono toccati.

Quando usarli:

• Usa strict per nuove collezioni in cui vuoi applicare completamente lo schema fin dall’inizio.
• Usa moderate quando applichi la convalida a collezioni che contengono già dati legacy o non strutturati.

validationAction

Questa opzione controlla come risponde MongoDB quando un documento viola le regole di convalida.

• error: l’operazione di scrittura viene rifiutata e viene restituito un errore di convalida.
• warn: la scrittura è accettata, ma il server registra internamente un avviso.

Importante: su MongoDB Atlas, gli avvisi di warn non sono visibili agli utenti — non li vedrai nell’interfaccia o nei log standard.

Quando usarle:

• Usa warn in sviluppo o durante un rollout graduale per monitorare le violazioni senza bloccare le scritture.
• Passa a error quando sei sicuro che la tua applicazione scriva documenti validi e vuoi imporre rigorosamente lo schema.

Esempio: passare da Warn a Error

Poniamo che tu sia partito così:

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

Dopo aver osservato il comportamento della tua applicazione, puoi passare a un’applicazione rigorosa:

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

Figura 6. Vengono usati due comandi collMod per modificare il comportamento di convalida della collezione validated_full. Il primo imposta validationAction su "warn" e validationLevel su "moderate," consentendo l’inserimento di documenti non validi registrando avvisi interni. Il secondo comando passa all’applicazione rigorosa impostando validationAction su "error" e validationLevel su "strict," garantendo che tutte le insert e gli update rispettino completamente lo schema definito.

Ora, qualsiasi insert o update non valido verrà bloccato con un messaggio di errore.

Errori comuni e suggerimenti per il debug

Quando lavori con la convalida dello schema, piccoli errori possono portare a messaggi fuorvianti — o peggio, documenti che aggirano silenziosamente le regole. Ecco alcuni dei problemi più frequenti e come evitarli:

Valori sbagliati per bsonType

Uno degli errori più comuni con $jsonSchema è confondere i tipi JSON con i "bsonType" di MongoDB. Mentre "string" e "array" sono immediati, altri come numeri e boolean possono essere insidiosi.

Per esempio:

• Usa "int" o "long" per i numeri interi.
• Usa "double" per i numeri in virgola mobile.
• Usa "bool" (non "boolean") per i valori vero/falso.
• Usa "object" per i sotto-documenti (non "dict" o "map").
• Usa "array" per le liste.

Se non sei sicuro di quale tipo abbia un campo, puoi ispezionare un documento usando typeof nella Mongo shell o rivedere i dati con MongoDB Compass.

Campi obbligatori mancanti negli aggiornamenti parziali

Quando usi $set, la convalida controlla solo i campi modificati. Se ti aspetti un controllo completo dello schema, assicurati di fare una sostituzione completa del documento o di usare validationLevel: "strict" con logica applicativa che imponga la struttura completa.

Array vuoti che passano quando non dovrebbero

Se dimentichi di specificare minItems, un array vuoto passerà:

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

Usa minItems: 1 per assicurarti che sia presente almeno un valore.

Nessun errore con la modalità warn

Come visto sopra, validationAction: "warn" non blocca le scritture né mostra errori in MongoDB Atlas. Registra solo internamente, quindi potrebbe sembrare che la convalida “non funzioni”.

Usa la modalità "error" durante lo sviluppo o in ambienti di test per intercettare i problemi in anticipo.

I percorsi dei campi annidati non vengono controllati se manca l’oggetto padre

Se imdb.rating è obbligatorio, ma imdb manca del tutto, MongoDB non controllerà il rating.

Per imporre la convalida sui campi annidati, assicurati che il loro oggetto padre sia obbligatorio o abbia bsonType: "object".

Interrogare o aggiornare documenti che non corrispondono allo schema

Dopo aver applicato la convalida a una collezione esistente, è spesso utile identificare i documenti che non rispettano il nuovo schema. Puoi farlo usando l’operatore $jsonSchema in una query con $nor o $not.

Esempio: trova i documenti non validi nella collezione movies

Supponi che il tuo schema richieda un title di tipo "string". Per trovare i documenti che non corrispondono, puoi eseguire:

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

Questo restituirà i documenti a cui manca title o che hanno title del tipo sbagliato.

Figura 7. Questa query usa $nor con $jsonSchema per trovare documenti nella collezione movies che non hanno un campo title di tipo string. Il risultato mostra un documento con _id: 683ce0050bd195c35e417534 che contiene solo il campo year, confermando che viola lo schema che richiede title. Questa tecnica è utile per identificare documenti non validi prima di applicare regole di convalida più rigorose.

Puoi usare questo approccio anche per:

• Auditare i documenti legacy prima di passare da "warn" a "error".
• Ripulire o correggere programmaticamente i documenti non validi.
• Generare report sulla conformità allo schema.

Conclusioni: dati puliti senza sacrificare la flessibilità

Il design senza schema di MongoDB è uno dei suoi punti di forza, ma non significa che tu debba lasciare i dati senza controllo. Con $jsonSchema puoi definire regole di convalida efficaci che impongono struttura sfruttando al contempo la flessibilità di MongoDB.

In questo articolo hai imparato a:

• Creare collezioni con regole di convalida.
• Applicare vincoli a collezioni nuove ed esistenti.
• Usare la convalida annidata per oggetti e array.
• Configurare modalità e azioni di convalida.
• Effettuare il debug e perfezionare i tuoi schemi con sicurezza.

Che tu stia costruendo una nuova app o aggiungendo struttura a un sistema legacy, la convalida dello schema ti dà gli strumenti per proteggere i dati senza rallentare lo sviluppo.

Prossimi passi e risorse

Vuoi approfondire? Dai un’occhiata a queste risorse:

• Documentazione su MongoDB Schema Validation 
• Documentazione su MongoDB JSON Schema
• Dati di esempio su MongoDB Atlas

Ti stai preparando ai colloqui? Queste domande top su MongoDB metteranno alla prova la tua comprensione di temi come la convalida dello schema e altro ancora. Vuoi certificare le tue competenze? Questa guida alla certificazione spiega tutto ciò che devi sapere per ottenere la certificazione MongoDB.

Ricorda: inizia in piccolo, testa con "warn" e passa a "error" quando sei sicuro — il te stesso del futuro (e i tuoi dati) ti ringrazieranno.