Validação do esquema do MongoDB: Um guia prático com exemplos

O MongoDB pode não ter esquema, mas isso não quer dizer que seus dados precisam ficar confusos.

Neste artigo, você vai aprender tudo, desde o básico da validação de esquema até casos de uso avançados usando o operador $jsonSchema. Você vai ver como fazer campos obrigatórios, restringir tipos de dados, aplicar padrões e validar documentos aninhados. 

Também vamos falar sobre como a validação funciona durante inserções e atualizações, como modificar coleções já existentes e quando usar diferentes níveis e ações de validação. 

No final, você vai estar confiante pra aplicar a validação de esquema nas suas coleções do MongoDB, mantendo seus dados organizados e previsíveis, sem perder a flexibilidade que o MongoDB tem.

Por que a validação de esquema é importante no MongoDB

O modelo de documento dinâmico do MongoDB oferece velocidade e flexibilidade, permitindo que documentos na mesma coleção tenham campos ou estruturas diferentes. Isso é uma grande vantagem durante o desenvolvimento inicial ou em iterações rápidas. Mas, essa mesma flexibilidade pode virar um problema, causando dados inconsistentes, incompletos ou inválidos conforme seu aplicativo cresce.

É aí que entraa validação de esquemas. Ele permite que você defina regras para seus documentos — como campos obrigatórios, tipos de dados específicos ou estruturas aninhadas — sem deixar de lado a flexibilidade do MongoDB.

Neste artigo, você vai aprender a usar o poderoso operador “ $jsonSchema ” do MongoDB para aplicar essas regras às suas coleções. Seja pra evitar inserções erradas em um novo aplicativo ou atualizar regras de validação em um banco de dados antigo, a validação de esquema ajuda a garantir que seus dados fiquem limpos, suas consultas previsíveis e seu aplicativo estável.

Se você é novo no MongoDB e no Python, este curso introdutório ao MongoDB é uma ótima maneira de começar a trabalhar com consultas e integrações antes de mergulhar na validação de esquemas.

Antes de começar

Para aproveitar ao máximo este guia, você vai precisar de acesso a um cluster do MongoDB Atlas. O plano gratuito é mais do que suficiente para acompanhar tudo.

Para deixar os conceitos bem claros e fáceis de usar, vamos usarum conjunto de dados de exemplo do MongoDB Atlas —, mais especificamente, o banco de dados sample_mflix. Esse conjunto de dados inclui coleções como filmes, comentários, usuários e cinemas, que vamos usar ao longo do artigo para mostrar cada exemplo. O conjunto de dados tem documentos com campos como objetos aninhados, matrizes, strings, números e campos opcionais.

Carregue o conjunto de dados de amostra (se necessário)

1. Vá para o painel do MongoDB Atlas.

2. Escolha o seu cluster, clique no botão “...” e selecione Carregar conjunto de dados de amostra.

3. Espera alguns minutos até que o banco de dados sample_mflix fique disponível.

Começando com a validação de esquema

Depois que o conjunto de dados estiver carregado, conecte-se ao cluster usando o MongoDB Shell (mongosh) ou o MongoDB Compass e, em seguida, mude para o conjunto de dados:

use sample_mflix

Explorando o conjunto de dados com findOne()

Vamos dar uma olhada em um dos documentos da coleção de filmes:

db.movies.findOne()

Aqui tá uma versão mais simples do que você pode ver:

Figura 1. Essa consulta usa findOne() pra pegar um documento de amostra da coleção de filmes no banco de dados sample_mflix. O resultado mostra vários campos, incluindo título, ano, gêneros e objetos aninhados, como imdb e tomatoes.viewer.

Esse documento tem uma mistura de valores escalares, matrizes e objetos aninhados, o que é ótimo pra mostrar várias técnicas de validação. Na próxima seção, vamos criar uma nova coleção com base nessa estrutura e definir nosso primeiro esquema de validação usando $jsonSchema.

Palavras-chave, extensões e limitações suportadas

A validação do MongoDB $jsonSchema é baseada na especificação JSON Schema Draft 4, com algumas modificações e omissões. Embora nem todos os recursos da especificação original sejam suportados, o MongoDB inclui um subconjunto focado e prático, adequado para validar documentos BSON.

Aqui estão algumas das palavras-chave mais usadas:

• bsonType: Palavra-chave de tipo específico do MongoDB (por exemplo, “string”, “int”, “array”, “object”)
• e necessário: Diz quais campos precisam estar lá
• o mínimo/máximo: Para validação de intervalos numéricos
• pattern: Para validação de formato de string usando expressões regulares
• enum: Limita um campo a um conjunto de valores permitidos.
• items, minItems, maxItems: Para validação de matriz
• propriedades: Define regras para campos dentro de um objeto
• additionalProperties: Controla se campos extras (não definidos) são permitidos.

O MongoDB omite de propósito alguns recursos avançados do esquema JSON completo, como:

• Referências de esquema ($ref).
• Lógica condicional (se/então/caso contrário).
• Operadores de composição (oneOf, allOf, anyOf).

Para ver a lista completa de opções disponíveis, dá uma olhada na documentação oficial do MongoDB $jsonSchema.

Neste artigo, vamos focar nas palavras-chave mais práticas e amplamente suportadas, suficientes para cobrir as necessidades comuns de validação do mundo real sem uma complexidade exagerada.

Para entender melhor como o MongoDB se encaixa no cenário NoSQL, dá uma olhada nesse tutorial completo.

Criando uma coleção com validação básica

Agora que já vimos como é a estrutura de um documento de filmes, vamos criar uma nova coleção que segue algumas regras básicas usando o $jsonSchema. Vamos começar com algumas limitações comuns:

• título: precisa ser uma string e é obrigatório
• ano: tem que ser um número inteiro e é obrigatório
• gêneros: precisa ser uma matriz de strings
• tempo de execução: tem que ser um número inteiro positivo

Vamos chamar essa nova coleção de “ validated_movies ”.

Criando a coleção

Execute o comando a seguir para criar a coleção com validação:

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

Colocar um documento válido

Agora, vamos inserir um documento que segue o esquema:

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

✅ Isso deve funcionar.

Inserindo um documento inválido

Tenta inserir um documento que não tem o campo “ title ”:

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

Isso vai dar erro de validação porque é preciso ter um campo chamado “ title ”.

Figura 2. O primeiro comando coloca um documento de filme válido na coleção validated_movies, passando todos os campos e tipos de dados necessários. O segundo comando tenta inserir um documento sem o campo de título necessário, resultando em um erro de validação.

Trabalhando com coleções já existentes

Você não precisa começar do zero para usar a validação de esquema. O MongoDB permite que você aplique regras de validação a coleções já existentes usando o comando “ collMod ”. Isso é super útil quando você quer dar uma estrutura a um conjunto de dados antigo sem mexer nos documentos que já existem.

Nesta seção, vamos aplicar um validador à coleção de filmes do banco de dados sample_mflix.

Adicionando um validador com collMod

Vamos seguir uma regra básica: Todo documento de filme precisa ter um campo “ title ” do tipo 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"
});

Verificando as regras de validação na coleção

Depois de mexer na coleção “ movies ” com o comando “ collMod ”, pode ser legal conferir quais regras de validação estão ativas no momento.

Para ver o validador de esquema atual, dá um grito:

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

Isso retorna o objeto $jsonSchema que define as regras de validação na coleção. É uma maneira útil de verificar se a sua configuração foi aplicada corretamente, principalmente depois de mudar de modo, como de aviso para erro, ou atualizar a estrutura dos campos obrigatórios.

Entendendo validationLevel e validationAction

• validationLevel: "moderate": Só valida os documentos que estão sendo inseridos ou atualizados. Os documentos que já existem e não batem com o esquema não vão dar erro.

• validationAction: "warn": Em vez de rejeitar gravações inválidas, o MongoDB registra um aviso. Isso é útil na produção quando você quer monitorar violações de esquema antes de aplicá-las.

Tenta inserir um documento que não siga o esquema:

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

Você vai ver um aviso nos registros, mas a gravação vai rolar. Você pode mudar a ação para “erro” mais tarde, pra garantir que a regra seja seguida, quando tiver certeza.

Figura 3. O comando insertOne() adiciona com sucesso um documento que viola a regra do esquema, porque a ação de validação está definida como “warn”. O MongoDB aceita a gravação, mas o campo título que tá faltando teria causado um erro de validação se “error” tivesse sido aplicado.

Validando documentos e matrizes aninhados

Os documentos do MongoDB geralmente têm estruturas aninhadas, tipo objetos dentro de objetos e matrizes de valores. Felizmente, $jsonSchema dá suporte à validação de ambos. Vamos ver como aplicar regras a subdocumentos e conteúdos de matrizes usando campos da coleção de filmes.

Validando um documento aninhado

Na coleção de filmes, cada documento tem um objeto imdb embutido com campos como rating, votes e id. Vamos seguir uma regra que garante:

• imdb é um objeto (se houver).
• imdb.rating é um número entre 0 e 10.

É assim que você definiria isso:

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

Testando o documento aninhado

✅ Inserção válida:

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

Inserção inválida (classificação fora do intervalo):

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

Isso vai gerar um erro de validação porque a classificação é maior que 10.      Figura 4. Essa operação de inserção não deu certo porque o campo de classificação dentro do objeto imdb aninhado passou do valor máximo permitido de 10, como está definido no esquema. O MongoDB mostra um erro de validação por causa da violação da regra $jsonSchema.

Validando matrizes

Você também pode aplicar restrições de matriz. Digamos que você queira garantir que:

• genres é uma matriz de strings.
• A matriz precisa ter pelo menos um item.

Adicione isso ao seu esquema:

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

Combinando várias restrições

Nas aplicações do mundo real, seus documentos muitas vezes precisam seguir várias regras de validação ao mesmo tempo — como campos obrigatórios, valores permitidos, tipos e estruturas aninhadas. Com o $jsonSchema, você pode juntar várias restrições numa única definição de esquema.

Vamos criar um exemplo mais completo usando a estrutura do documento “filmes”. Vamos seguir essas regras:

• título: obrigatório, deve ser uma string
• ano: obrigatório, número inteiro, ≥ 1888
• classificado: opcional, mas precisa combinar com um conjunto de valores pré-definidos
• gêneros: tem que ser uma matriz de strings que não esteja vazia
• imdb.rating: número entre 0 e 10
• tomatoes.viewer.rating: opcional, número entre 0 e 5

Criando uma coleção validada

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

Como colocar um documento válido: 

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

Inserindo um documento inválido:

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

Isso vai dar errado por causa de:

• Valor inválido para rated.
• Esvazia a matriz “ genres ”.
• imdb.rating mais de 10.
• tomatoes.viewer.rating mais de 5.

Figura 5. Essa operação de inserção falhou por causa de várias violações de esquema na coleção validated_full. O campo rated tem um valor que não é permitido pela enumeração, genres é uma matriz vazia que não segue a regra minItems, imdb.rating passa do máximo de 10 e tem o tipo errado, e tomatoes.viewer.rating passa do máximo permitido de 5. O MongoDB não aceita a inserção e mostra um erro de validação bem detalhado.

Níveis de validação e ações explicados

O MongoDB te dá um controle bem detalhado sobre como e quando a validação do esquema é aplicada. Ao definir regras de validação, duas opções influenciam o comportamento do seu banco de dados:

• validationLevel: Quando a regra deve ser aplicada
• validationAction: O que rola quando um documento não bate com a regra?

validationLevel

Essa opção controla quais operações passam pela validação do esquema.

• rigoroso: Todas as inserções e atualizações precisam estar de acordo com o esquema. Esse é o modo padrão e mais seguro.
• moderado: Só os documentos que estão sendo inseridos ou atualizados são validados. Os documentos que já existem, mesmo que não valham mais, ficam como estão.

Quando usar:

• Use strict para novas coleções onde você quer aplicar totalmente o esquema desde o início.
• Use com moderação ao aplicar a validação a coleções que já têm dados antigos ou não estruturados.

validationAction

Essa opção controla como o MongoDB reage quando um documento não segue as regras de validação.

• erro: A operação de gravação é rejeitada e um erro de validação é retornado.
• warn: A gravação foi aceita, mas o servidor registrou um aviso internamente.

Importante: No MongoDB Atlas, os avisos do warn não aparecem para os usuários — você não vai vê-los na interface do usuário nem nos logs padrão.

Quando usar:

• Use o aviso durante o desenvolvimento ou durante a implementação gradual para monitorar violações sem bloquear gravações.
• Mude para erro quando tiver certeza de que seu aplicativo está escrevendo documentos válidos e quiser aplicar o esquema de forma estrita.

Exemplo: Mudando de Aviso para Erro

Digamos que você começou com isso:

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

Depois de ver como o aplicativo tá funcionando, dá pra mudar pra uma aplicação mais rígida:

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

Figura 6. Dois comandos collMod são usados para modificar o comportamento de validação da coleção validated_full. O primeiro define a ação de validação como “warn” e o nível de validação como “moderate”, permitindo que documentos inválidos sejam inseridos enquanto registros internos de avisos são gerados. O segundo comando muda para a aplicação rigorosa, definindo validationAction como “error” e validationLevel como “strict”, garantindo que todas as inserções e atualizações estejam totalmente em conformidade com o esquema definido.

Agora, qualquer inserção ou atualização inválida vai ser bloqueada com uma mensagem de erro.

Erros comuns e dicas de depuração

Quando você tá lidando com validação de esquema, pequenos erros podem causar confusão — ou pior, documentos podem passar direto pelas suas regras sem você perceber. Aqui estão alguns dos problemas mais comuns e como evitá-los:

Valores errados de bsonType

Um dos erros mais comuns ao usar $jsonSchema é confundir os tipos JSON com o “bsonType” do MongoDB. Enquanto “string” e “array” são simples, outros como números e booleanos podem ser complicados.

Por exemplo:

• Use “int” ou “long” para números inteiros.
• Use “double” para números de ponto flutuante.
• Use “bool” (não “boolean”) para valores verdadeiros/falsos.
• Use “object” para subdocumentos (não “dict” ou “map”).
• Use “array” para listas.

Se você não tem certeza de como um campo está armazenado, pode dar uma olhada no documento usando typeof no shell do Mongo ou conferir os dados usando o MongoDB Compass.

Campos obrigatórios faltando em atualizações parciais

Quando você usa $set, a validação só verifica os campos que estão sendo modificados. Se você está esperando uma verificação completa do esquema, certifique-se de fazer uma substituição completa do documento ou usar validationLevel: "strict" com a lógica do aplicativo impondo a estrutura completa.

Arrays vazios passando quando não deveriam

Se você esquecer de colocar minItems, vai passar uma matriz vazia:

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

Use minItems: 1 para garantir que pelo menos um valor esteja presente.

Sem erro com o modo de aviso

Como falamos antes, o validationAction: "warn" não bloqueia gravações nem mostra erros no MongoDB Atlas. Ele só registra internamente, então a validação pode parecer que “não funciona”.

Use o modo “erro” durante o desenvolvimento ou em ambientes de teste para detectar problemas logo no início.

Os caminhos de campos aninhados não são verificados se o objeto pai estiver faltando.

Se imdb.rating for necessário, mas imdb estiver faltando, o MongoDB não vai verificar rating.

Para fazer a validação em campos aninhados, certifique-se de que o objeto pai deles seja obrigatório ou tenha um bsonType: "object".

Consultar ou atualizar documentos que não correspondem ao esquema

Depois de aplicar a validação a uma coleção já existente, muitas vezes é útil identificar os documentos que não estão de acordo com o novo esquema. Você pode fazer isso usando o operador “ $jsonSchema ” numa consulta com “ $nor ” ou “ $not ”.

Exemplo: Encontre documentos inválidos na coleção de filmes

Digamos que seu esquema precisa de um título do tipo “string”. Para encontrar documentos que não correspondem, você pode executar:

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

Isso vai mostrar os documentos que não têm título ou têm um título errado.

Figura 7. Essa consulta usa $nor com $jsonSchema pra achar documentos na coleção filmes que não têm um campo título do tipo string. O resultado mostra um documento com _id: 683ce0050bd195c35e417534 que só tem o campo do ano, mostrando que não tá de acordo com o esquema que precisa de um título. Essa técnica é útil pra identificar documentos inválidos antes de aplicar regras de validação mais rígidas.

Você também pode usar essa abordagem para:

• Dá uma olhada nos documentos antigos antes de mudar de “aviso” para “erro”.
• Limpe ou conserte documentos inválidos de forma programada.
• Crie relatórios sobre a conformidade do esquema.

Resumo: Limpe os dados sem perder a flexibilidade

O design sem esquema do MongoDB é um dos seus maiores pontos fortes, mas isso não quer dizer que você deva deixar seus dados sem controle. Com o $jsonSchema, você pode definir regras de validação poderosas que garantem a estrutura enquanto aproveita a flexibilidade do MongoDB.

Neste artigo, você aprendeu como:

• Crie coleções com regras de validação.
• Aplique restrições a coleções novas e já existentes.
• Use validação aninhada para objetos e matrizes.
• Configure os modos e ações de validação.
• Depure e refine seus esquemas com confiança.

Seja pra criar um aplicativo totalmente novo ou dar uma estrutura melhor a um sistema antigo, a validação de esquema te dá as ferramentas pra proteger seus dados sem deixar o desenvolvimento mais lento.

Próximos passos e recursos

Quer saber mais? Dá uma olhada nesses recursos:

• Documentos sobre validação de esquemas do MongoDB 
• Documentação do esquema JSON do MongoDB
• Dados de amostra no MongoDB Atlas

Preparando-se para entrevistas? Essas perguntas mais difíceis sobre o MongoDB vão testar sua compreensão de tópicos como validação de esquema e muito mais. Quer validar suas habilidades no yo? Este guia de certificação mostratudo que você precisa saber pra conseguir a certificação no MongoDB.

Lembre-se: comece aos poucos, teste com “aviso” e passe para “erro” quando estiver confiante — seu futuro (e seus dados) vão agradecer.