JSON Schema es un vocabulario que permite anotar y validar documentos JSON. Se puede usar JSON schema para especificar reglas de validación para los campos en un formato legible por humanos.
Context
MongoDB admite el borrador 4 del esquema JSON, incluido especificación básicay la especificación de validación, con algunas diferencias. Para más detalles, consulte Extensiones y omisiones.
Para obtener más información sobre JSON Schema, consulta el sitio web oficial.
Restricciones
No puedes especificar la validación del esquema para:
Colecciones en el
admin,localyconfigbases de datos
Si tiene Cifrado a nivel de campo del lado del cliente o Queryable Encryption habilitado en una colección, la validación está sujeta a las siguientes restricciones:
Para CSFLE, al ejecutar
collMod, la librería libmongocrypt prefiere el esquema de cifrado JSON especificado en el comando. Esto permite establecer un esquema en una colección que aún no lo tiene.Para Queryable Encryption, cualquier JSON schema que incluya un campo cifrado resulta en un error de análisis de query.
Pasos
En este ejemplo, se crea una colección students con reglas de validación y se pueden observar los resultados después de intentar insertar un documento no válido.
Realizar la conexión a la implementación de MongoDB.
Para conectarse a una instancia local de MongoDB o a una implementación de MongoDB Atlas usando mongosh, consulta los pasos en Conéctese a una implementación o Conéctese vía mongosh.
Crea una colección con validación.
En mongosh, ejecute el siguiente comando para crear una colección students y use el operador $jsonSchema para establecer reglas de validación de esquema:
db.createCollection("students", { validator: { $jsonSchema: { bsonType: "object", title: "Student Object Validation", required: [ "address", "major", "name", "year" ], properties: { name: { bsonType: "string", description: "'name' must be a string and is required" }, year: { bsonType: "int", minimum: 2017, maximum: 3017, description: "'year' must be an integer in [ 2017, 3017 ] and is required" }, gpa: { bsonType: [ "double" ], description: "'gpa' must be a double if the field exists" } } } } } )
Tip
Aclara las reglas con los campos de título y descripción
Puede utilizar los campos title y description para proporcionar una explicación de las reglas de validación cuando estas no son inmediatamente claras. Cuando un documento no pasa la validación, MongoDB incluye estos campos en el resultado de error.
Confirma que la validación impide documentos no válidos.
Ejecuta el siguiente comando. La operación de inserción falla porque gpa es un número entero cuando validator requiere un double.
db.students.insertOne( { name: "Alice", year: Int32( 2019 ), major: "History", gpa: Int32(3), address: { city: "NYC", street: "33rd Street" } } )
MongoServerError: Document failed validation Additional information: { failingDocumentId: ObjectId("630d093a931191850b40d0a9"), details: { operatorName: '$jsonSchema', title: 'Student Object Validation', schemaRulesNotSatisfied: [ { operatorName: 'properties', propertiesNotSatisfied: [ { propertyName: 'gpa', description: "'gpa' must be a double if the field exists", details: [ { operatorName: 'bsonType', specifiedAs: { bsonType: [ 'double' ] }, reason: 'type did not match', consideredValue: 3, consideredType: 'int' } ] } ] } ] } }
Tip
Por defecto, mongosh imprime objetos anidados hasta seis niveles de profundidad. Para imprimir todos los objetos anidados en su máxima profundidad, configura inspectDepth a Infinity.
config.set("inspectDepth", Infinity)
Insert a valid document.
Si cambia el valor del campo gpa a un tipo double, la operación de inserción se realiza con éxito. Ejecute el siguiente comando para insertar el documento válido:
db.students.insertOne( { name: "Alice", year: Int32(2019), major: "History", gpa: Double(3.0), address: { city: "NYC", street: "33rd Street" } } )
Query para el documento válido.
Para confirmar que has insertado correctamente el documento, ejecuta el siguiente comando para el query de la colección students:
db.students.find()
[ { _id: ObjectId("62bb413014b92d148400f7a5"), name: 'Alice', year: 2019, major: 'History', gpa: 3, address: { city: 'NYC', street: '33rd Street' } } ]
Tip
Si estás conectado a una implementación de Atlas, también puedes ver y filtrar el documento en la Interfaz de usuario de Atlas.
Información Adicional
Puedes combinar la validación de esquema JSON con la validación del operador del query.
Por ejemplo, considere una colección sales con esta validación de esquema:
db.createCollection("sales", { validator: { "$and": [ // Validation with query operators { "$expr": { "$lt": ["$lineItems.discountedPrice", "$lineItems.price"] } }, // Validation with JSON Schema { "$jsonSchema": { "properties": { "items": { "bsonType": "array" } } } } ] } } )
La validación anterior aplica estas reglas para los documentos de la colección sales:
lineItems.discountedPricedebe ser menor quelineItems.price. Esta regla se especifica utilizando el operador$lt.El campo
itemsdebe ser un arreglo. Esta regla se especifica usando$jsonSchema.
Obtén más información
Para ver la lista completa de palabras clave permitidas en un esquema JSON, consulta Palabras clave disponibles.
Para restringir los valores que puede contener un determinado campo, consulte Especificar valores permitidos para el campo.
Para evitar problemas con la validación de esquema JSON, consulta Consejos para la validación de esquema JSON.