Validación del esquema de MongoDB: Guía práctica con ejemplos

MongoDB puede carecer de esquema, pero eso no significa que tus datos tengan que estar desordenados.

En este artículo, aprenderás todo lo necesario, desde los conceptos básicos de la validación de esquemas hasta casos de uso avanzados con el operador « $jsonSchema ». Explorarás cómo hacer obligatorios los campos obligatorios, restringir los tipos de datos, aplicar patrones y validar documentos anidados. 

También veremos cómo funciona la validación durante las inserciones y actualizaciones, cómo modificar colecciones existentes y cuándo utilizar diferentes niveles y acciones de validación. 

Al final, te sentirás seguro a la hora de aplicar la validación de esquemas a tus colecciones de MongoDB, manteniendo tus datos limpios y predecibles, sin renunciar a la flexibilidad por la que se conoce a MongoDB.

Por qué es importante la validación de esquemas en MongoDB

El modelo de documentos dinámicos de MongoDB ofrece velocidad y flexibilidad al permitir que los documentos de una misma colección tengan campos o estructuras diferentes. Esto supone una gran ventaja durante las primeras fases de desarrollo o en iteraciones rápidas. Sin embargo, esa misma flexibilidad puede convertirse rápidamente en un inconveniente, dando lugar a datos incoherentes, incompletos o inválidos a medida que tu aplicación crece.

Ahí es donde entra en juegola validación de esquemas. Te permite definir reglas para tus documentos, como campos obligatorios, tipos de datos específicos o estructuras anidadas, sin renunciar a la flexibilidad de MongoDB.

En este artículo, aprenderás a utilizar el potente operador « $jsonSchema » (excluir por) de MongoDB para aplicar estas reglas a tus colecciones. Tanto si deseas evitar inserciones malformadas en una nueva aplicación como si deseas actualizar las reglas de validación en una base de datos heredada, la validación de esquemas te ayuda a garantizar que tus datos se mantengan limpios, tus consultas sean predecibles y tu aplicación siga siendo estable.

Si eres nuevo en el trabajo con MongoDB y Python, este curso introductorio a MongoDB es una forma estupenda de familiarizarte con las consultas y las integraciones antes de sumergirte en la validación de esquemas.

Antes de comenzar

Para sacar el máximo partido a esta guía, necesitarás acceso a un clúster de MongoDB Atlas. El plan gratuito es más que suficiente para seguir el curso.

Para que los conceptos sean lo más claros y aplicables posible, utilizaremosun conjunto de datos de muestra de MongoDB Atlas:, concretamente, la base de datos sample_mflix. Este conjunto de datos incluye colecciones como películas, comentarios, usuarios y cines, a los que haremos referencia a lo largo del artículo para ilustrar cada ejemplo. El conjunto de datos incluye documentos con campos como objetos anidados, arreglos, cadenas, números y campos opcionales.

Carga el conjunto de datos de muestra (si es necesario).

1. Ve al panel de control de MongoDB Atlas.

2. Selecciona tu clúster, haz clic en el botón «...» y selecciona Cargar conjunto de datos de muestra.

3. Espera unos minutos hasta que la base de datos sample_mflix esté disponible.

Introducción a la validación de esquemas

Una vez cargado el conjunto de datos, conéctate al clúster mediante MongoDB Shell (mongosh) o MongoDB Compass y, a continuación, cambia al conjunto de datos:

use sample_mflix

Explorar el conjunto de datos con findOne()

Veamos uno de los documentos de la colección de películas:

db.movies.findOne()

Aquí tienes una versión simplificada de lo que podrías ver:

Figura 1. Esta consulta utiliza findOne() para recuperar un único documento de muestra de la colección movies de la base de datos sample_mflix. El resultado muestra varios campos, incluyendo título, año, géneros y objetos anidados como imdb y tomatoes.viewer.

Este documento contiene una mezcla de valores escalares, arreglos y objetos anidados, lo que lo hace ideal para demostrar una amplia gama de técnicas de validación. En la siguiente sección, crearemos una nueva colección basada en esta estructura y definiremos nuestro primer esquema de validación utilizando $jsonSchema.

Palabras clave, extensiones y limitaciones compatibles

La validación de MongoDB $jsonSchema se basa en la especificación JSON Schema Draft 4, con algunas modificaciones y omisiones. Aunque no todas las características de la especificación original son compatibles, MongoDB incluye un subconjunto específico y práctico adecuado para validar documentos BSON.

Estas son algunas de las palabras clave más utilizadas:

• bsonType: Palabra clave de tipo específico de MongoDB (por ejemplo, «string», «int», «array», «object»).
• requerido: Especifica qué campos deben estar presentes.
• : mínimo/máximo Para la validación de rangos numéricos
• patrón: Para validar el formato de cadenas utilizando expresiones regulares.
• enum: Restringe un campo a un conjunto de valores permitidos.
• items, minItems, maxItems: Para la validación de arreglos
• Propiedades: Define reglas para los campos dentro de un objeto.
• propiedades adicionales: Controla si se permiten campos adicionales (no definidos).

MongoDB omite intencionadamente algunas funciones avanzadas del esquema JSON completo, como por ejemplo:

• Referencias de esquema ($ref).
• Lógica condicional (si/entonces/si no).
• Operadores de composición (oneOf, allOf, anyOf).

Para obtener la lista completa de opciones compatibles, consulta la documentación oficial de MongoDB $jsonSchema.

En este artículo, nos centraremos en las palabras clave más prácticas y ampliamente compatibles, suficientes para cubrir las necesidades de validación habituales en el mundo real sin una complejidad abrumadora.

Para comprender mejor cómo encaja MongoDB en el panorama NoSQL, explora este completo tutorial.

Creación de una colección con validación básica

Ahora que ya hemos visto la estructura de un documento de películas, creemos una nueva colección que aplique algunas reglas básicas utilizando $jsonSchema. Comenzaremos con algunas limitaciones comunes:

• título: debe ser una cadena y es obligatorio
• año: debe ser un número entero y es obligatorio
• géneros: debe ser un arreglo de cadenas
• tiempo de ejecución: debe ser un número entero positivo

Llamaremos a esta nueva colección « validated_movies » (El arte de la perfección).

Creación de la colección

Ejecuta el siguiente comando para crear la colección con validación:

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

Insertar un documento válido

Ahora, insertemos un documento que siga el esquema:

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

✅ Esto debería funcionar.

Insertar un documento no válido

Intenta insertar un documento al que le falte el campo title:

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

❌ Esto fallará con un error de validación porque se requiere title.

Figura 2. El primer comando inserta un documento de película válido en la colección validated_movies, pasando todos los campos y tipos de datos requeridos. El segundo comando intenta insertar un documento sin el campo de título requerido, lo que da lugar a un error de validación.

Trabajar con colecciones existentes

No es necesario empezar desde cero para utilizar la validación de esquemas. MongoDB te permite aplicar reglas de validación a colecciones existentes mediante el comando collMod. Esto resulta especialmente útil cuando deseas añadir estructura a un conjunto de datos heredado sin afectar a los documentos existentes.

En esta sección, aplicaremos un validador a la colección de películas de la base de datos sample_mflix.

Añadir un validador con collMod

Apliquemos una regla básica: Todos los documentos de películas deben tener un campo « title » (tipo de película) de tipo cadena.

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

Inspección de las reglas de validación en la colección

Después de modificar la colección « movies » mediante el comando « collMod », es posible que desees confirmar qué reglas de validación están activas actualmente.

Para comprobar el validador de esquemas actual, ejecuta:

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

Devuelve el objeto $jsonSchema que define las reglas de validación de la colección. Es una forma útil de verificar que la configuración se ha aplicado correctamente, especialmente después de cambiar de modo, como de advertencia a error, o de actualizar la estructura de los campos obligatorios.

Comprender validationLevel y validationAction

• validationLevel: «moderado»: Solo valida los documentos que se están insertando o actualizando. Los documentos existentes que no coincidan con el esquema no generarán errores.

• validationAction: «warn»: En lugar de rechazar las escrituras no válidas, MongoDB registra una advertencia. Esto resulta útil en producción cuando deseas supervisar las infracciones de esquema antes de aplicarlas.

Intenta insertar un documento que infrinja el esquema:

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

Verás una advertencia en los registros, pero la escritura se realizará correctamente. Puedes cambiar la acción a «error» más adelante para aplicar la regla de forma estricta una vez que estés seguro.

Figura 3. El comando insertOne() añade correctamente un documento que incumple la regla del esquema, ya que la acción de validación está establecida en «warn». MongoDB acepta la escritura, pero el campo de título que falta habría provocado un error de validación si se hubiera aplicado «error».

Validación de documentos anidados y arreglos

Los documentos de MongoDB suelen incluir estructuras anidadas, como objetos dentro de objetos y arreglos de valores. Afortunadamente, $jsonSchema admite la validación de ambos. Exploremos cómo aplicar reglas a subdocumentos y contenidos de arreglos utilizando campos de la colección movies.

Validación de un documento anidado

En la colección de películas, cada documento incluye un objeto imdb incrustado con campos como rating, votes y id. Implantemos una norma que garantice:

• imdb es un objeto (si está presente).
• imdb.rating es un número entre 0 y 10.

Así es como se definiría eso:

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

Prueba del documento anidado

✅ Insert válido:

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

❌ Inserción no válida (calificación fuera de rango):

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

Esto generará un error de validación porque la calificación es superior a 10.      Figura 4. Esta operación de inserción falla porque el campo rating dentro del objeto imdb anidado excede el valor máximo permitido de 10, tal y como se define en el esquema. MongoDB genera un error de validación debido a la violación de la regla $jsonSchema.

Validación de arreglos

También puedes aplicar restricciones de arreglo. Supongamos que quieres asegurarte de que:

• genres es un arreglo de cadenas.
• El arreglo debe tener al menos un elemento.

Añade esto a tu esquema:

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

Combinación de múltiples restricciones

En aplicaciones del mundo real, tus documentos a menudo deben cumplir varias reglas de validación a la vez, que abarcan campos obligatorios, valores permitidos, tipos y estructuras anidadas. Con $jsonSchema, puedes combinar fácilmente múltiples restricciones en una única definición de esquema.

Construyamos un ejemplo más completo utilizando la estructura del documento de películas. Aplicaremos las siguientes normas:

• título: obligatorio, debe ser una cadena
• año: obligatorio, entero, ≥ 1888
• clasificado: opcional, pero debe coincidir con un conjunto predefinido de valores
• géneros: debe ser un arreglo no vacío de cadenas
• imdb.rating: número entre 0 y 10
• tomatoes.viewer.rating: opcional, número entre 0 y 5

Creación de una colección 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"
                }
              }
            }
          }
        }
      }
    }
  }
});

Insertar un 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 } }
});

Inserción de un documento no válido:

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

Esto fallará debido a:

• Valor no válido para rated.
• Arreglo vacío de genres.
• imdb.rating superando los 10.
• tomatoes.viewer.rating superando los 5.

Figura 5. Esta operación de inserción falla debido a múltiples violaciones de esquema en la colección validated_full. El campo rated contiene un valor no permitido por la enumeración, genres es un arreglo vacío que infringe la regla minItems, imdb.rating supera el máximo de 10 y tiene un tipo incorrecto, y tomatoes.viewer.rating supera el máximo permitido de 5. MongoDB rechaza la inserción con un error de validación detallado.

Explicación de los niveles de validación y las acciones

MongoDB te ofrece un control preciso sobre cómo y cuándo se aplica la validación del esquema. Al definir las reglas de validación, hay dos opciones que influyen en el comportamiento de la base de datos:

• nivel de validación: Cuándo debe aplicarse la norma
• validaciónAcción: ¿Qué sucede cuando un documento no cumple la regla?

validaciónNivel

Esta opción controla qué operaciones están sujetas a la validación del esquema.

• estricto: Todas las inserciones y actualizaciones deben ajustarse al esquema. Este es el modo predeterminado y más seguro.
• moderado: Solo se validan los documentos que se insertan o actualizan. Los documentos existentes, aunque no sean válidos, no se modifican.

Cuándo utilizarlo:

• Utiliza strict para nuevas colecciones en las que quieras aplicar el esquema de forma estricta desde el principio.
• Utiliza con moderación la validación en colecciones que ya contienen datos heredados o no estructurados.

validaciónAcción

Esta opción controla cómo responde MongoDB cuando un documento incumple las reglas de validación.

• error: La operación de escritura se rechaza y se devuelve un error de validación.
• advertir: La escritura se acepta, pero el servidor registra una advertencia internamente.

Importante: En MongoDB Atlas, las advertencias de warn no son visibles para los usuarios; no las verás en la interfaz de usuario ni en los registros estándar.

Cuándo utilizarlo:

• Utiliza warn durante el desarrollo o durante la implementación gradual para supervisar las infracciones sin bloquear las escrituras.
• Cambia a error cuando estés seguro de que tu aplicación está escribiendo documentos válidos y quieras aplicar estrictamente el esquema.

Ejemplo: Cambiar de «Advertencia» a «Error»

Supongamos que empezaste con esto:

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

Después de observar el comportamiento de tu aplicación, puedes cambiar a la aplicación estricta:

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

Figura 6. Se utilizan dos comandos collMod para modificar el comportamiento de validación de la colección validated_full. El primero establece validationAction en «warn» y validationLevel en «moderate», lo que permite insertar documentos no válidos mientras se registran advertencias internas. El segundo comando cambia a la aplicación estricta estableciendo validationAction en «error» y validationLevel en «strict», lo que garantiza que todas las inserciones y actualizaciones deben cumplir totalmente con el esquema definido.

Ahora, cualquier inserción o actualización no válida se bloqueará con un mensaje de error.

Errores comunes y consejos para la depuración

Cuando trabajas con la validación de esquemas, los pequeños errores pueden dar lugar a errores confusos o, lo que es peor, a que los documentos eludan tus reglas sin que te des cuenta. A continuación, se indican algunos de los problemas más frecuentes y cómo evitarlos:

Valores incorrectos de bsonType

Uno de los errores más comunes al utilizar $jsonSchema es confundir los tipos JSON con el «bsonType» de MongoDB. Mientras que «cadena» y «arreglo» son sencillos, otros como números y booleanos pueden resultar complicados.

Por ejemplo:

• Utiliza «int» o «long» para números enteros.
• Utiliza «doble» para los números de coma flotante.
• Utiliza «bool» (no «boolean») para los valores verdadero/falso.
• Utiliza «objeto» para los subdocumentos (no «dict» ni «map»).
• Utiliza «arreglo» para las listas.

Si no estás seguro de en qué tipo se almacena un campo, puedes inspeccionar un documento utilizando typeof en el terminal de Mongo o revisar los datos utilizando MongoDB Compass.

Faltan campos obligatorios en las actualizaciones parciales

Cuando se utiliza $set, la validación solo comprueba los campos que se están modificando. Si esperas una comprobación completa del esquema, asegúrate de que estás realizando una sustitución completa del documento o de que estás utilizando validationLevel: "strict" con una lógica de aplicación que imponga la estructura completa.

Arreglos vacíos que pasan cuando no deberían

Si olvidas especificar minItems, se pasará un arreglo vacío:

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

Utiliza minItems: 1 para asegurarte de que hay al menos un valor presente.

Sin errores con el modo de advertencia

Como se ha mencionado anteriormente, validationAction: "warn" no bloquea las escrituras ni muestra errores en MongoDB Atlas. Solo se registra internamente, por lo que la validación puede parecer que «no funciona».

Utiliza el modo «error» durante el desarrollo o en entornos de prueba para detectar problemas de forma temprana.

Las rutas de campos anidados no se comprueban si falta el objeto principal.

Si se requiere imdb.rating, pero imdb falta por completo, MongoDB no comprobará rating.

Para aplicar la validación en campos anidados, asegúrate de que su objeto principal sea obligatorio o tenga un bsonType: "object".

Consultar o actualizar documentos que no coinciden con el esquema

Después de aplicar la validación a una colección existente, suele ser útil identificar los documentos que no se ajustan al nuevo esquema. Puedes hacerlo utilizando el operador « $jsonSchema » en una consulta con « $nor » o « $not ».

Ejemplo: Buscar documentos no válidos en la colección de películas

Supongamos que tu esquema requiere un título de tipo «string». Para encontrar documentos que no coincidan, puedes ejecutar:

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

Esto devolverá los documentos que no tienen título o tienen un título de tipo incorrecto.

Figura 7. Esta consulta utiliza $nor con $jsonSchema para buscar documentos en la colección movies que no tengan un campo title de tipo string. El resultado muestra un documento con _id: 683ce0050bd195c35e417534 que solo contiene el campo año, lo que confirma que incumple el esquema que exige un título. Esta técnica es útil para identificar documentos no válidos antes de aplicar reglas de validación más estrictas.

También puedes utilizar este enfoque para:

• Audita los documentos heredados antes de cambiar de «advertencia» a «error».
• Limpia o corrige documentos no válidos mediante programación.
• Genera informes sobre el cumplimiento de los esquemas.

Resumen: Limpia los datos sin sacrificar la flexibilidad

El diseño sin esquemas de MongoDB es una de sus mayores fortalezas, pero eso no significa que debas dejar tus datos sin controlar. Con $jsonSchema, puedes definir potentes reglas de validación que imponen una estructura al tiempo que aprovechan la flexibilidad de MongoDB.

A lo largo de este artículo, has aprendido a:

• Crea colecciones con reglas de validación.
• Aplica restricciones a colecciones nuevas y existentes.
• Utiliza la validación anidada para objetos y arreglos.
• Configura los modos y acciones de validación.
• Depura y perfecciona tus esquemas con confianza.

Tanto si estás creando una aplicación desde cero como si estás añadiendo estructura a un sistema heredado, la validación de esquemas te proporciona las herramientas necesarias para proteger tus datos sin ralentizar el desarrollo.

Próximos pasos y recursos

¿Quieres profundizar más? Echa un vistazo a estos recursos:

• Documentación sobre validación de esquemas de MongoDB 
• Documentación sobre el esquema JSON de MongoDB
• Datos de muestra en MongoDB Atlas

¿Te estás preparando para una entrevista? Estas preguntas más importantes sobre MongoDB pondrán a prueba tu comprensión de temas como la validación de esquemas y mucho más. ¿Quieres validar tus habilidades en yo? Esta guía de certificación describetodo lo que necesitas saber para obtener la certificación en MongoDB.

Recuerda, empieza poco a poco, prueba con «warn» y pasa a «error» una vez que te sientas seguro: tu yo futuro (y tus datos) te lo agradecerán.