/ /

Consulta y proyección

query de evaluación

Docs Home

Manual de MongoDB

Referencia

Operadores

Consulta y proyección

query de evaluación

$jsonSchema

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 5.0, consulta el Procedimientos de actualización de MongoDB.6.0

Definición

$jsonSchema

El operador $jsonSchema coincide con documentos que cumplen el JSON schema especificado.

La expresión del operador $jsonSchema tiene la siguiente sintaxis:

{ $jsonSchema: <JSON Schema object> }

Donde el JSON schema está formateado según el borrador 4 del estándar de JSON schema.

{ <keyword1>: <value1>, ... }

Por ejemplo:

{
  $jsonSchema: {
     required: [ "name", "major", "gpa", "address" ],
     properties: {
        name: {
           bsonType: "string",
           description: "must be a string and is required"
        },
        address: {
           bsonType: "object",
           required: [ "zipcode" ],
           properties: {
               "street": { bsonType: "string" },
               "zipcode": { bsonType: "string" }
           }
        }
     }
  }
}

Para una lista de las palabras clave compatibles con MongoDB, consulte Palabras clave disponibles.

Nota

MongoDB admite 4 el borrador del esquema JSON, incluyendo la especificación principal y la especificación de validación, con algunas diferencias. Consulte Extensiones y omisiones para obtener más información.

Para obtener más información sobre JSON Schema, consulta el sitio web oficial.

Comportamiento

Compatibilidad de características

La featureCompatibilityVersion debe establecerse en "3.6" o superior para poder usar $jsonSchema.

Validador de Documentos

Puedes utilizar $jsonSchema en un validador de documentos para aplicar el esquema especificado en las operaciones de inserción y actualización:

db.createCollection( <collection>, { validator: { $jsonSchema: <schema> } } )
db.runCommand( { collMod: <collection>, validator:{ $jsonSchema: <schema> } } )

Condiciones de query

Puedes utilizar $jsonSchema en las condiciones de query para las operaciones de lectura y escritura para encontrar documentos en la colección que cumplan el esquema especificado:

db.collection.find( { $jsonSchema: <schema> } )
db.collection.aggregate( [ { $match: { $jsonSchema: <schema> } } ] )
db.collection.updateMany( { $jsonSchema: <schema> }, <update> )
db.collection.deleteOne( { $jsonSchema: <schema> } )

Para buscar documentos en la colección que no cumplan con el esquema especificado, utiliza la expresión $jsonSchema en una expresión $nor. Por ejemplo:

db.collection.find( { $nor: [ { $jsonSchema: <schema> } ] } )
db.collection.aggregate( [ { $match: { $nor: [ { $jsonSchema: <schema> } ] } }, ... ] )
db.collection.updateMany( { $nor: [ { $jsonSchema: <schema> } ] }, <update> )
db.collection.deleteOne( { $nor: [ { $jsonSchema: <schema> } ] } )

Ejemplos

Validación de esquema

El siguiente método db.createCollection() crea una colección llamada students y usa el operador $jsonSchema para establecer reglas de validación de esquema:

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "name", "year", "major", "address" ],
         properties: {
            name: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               description: "must be an integer in [ 2017, 3017 ] and is required"
            },
            major: {
               enum: [ "Math", "English", "Computer Science", "History", null ],
               description: "can only be one of the enum values and is required"
            },
            gpa: {
               bsonType: [ "double" ],
               description: "must be a double if the field exists"
            },
            address: {
               bsonType: "object",
               required: [ "city" ],
               properties: {
                  street: {
                     bsonType: "string",
                     description: "must be a string if the field exists"
                  },
                  city: {
                     bsonType: "string",
                     "description": "must be a string and is required"
                  }
               }
            }
         }
      }
   }
} )

Dado el validator creado para la colección, la siguiente operación de inserción fallará porque gpa es un entero cuando el validator requiere un double.

db.students.insertOne( {
   name: "Alice",
   year: Int32( 2019 ),
   major: "History",
   gpa: Int32( 3 ),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )

La operación devuelve el siguiente error:

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("61aa577f666a50a8fccd7ec2"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'gpa',
            description: 'must be a double if the field exists',
            details: [ [Object] ]
          }
        ]
      }
    ]
  }
}

Después de cambiar gpa a un doble, la inserción se realiza correctamente:

db.students.insertOne( {
   name: "Alice",
   year: NumberInt(2019),
   major: "History",
   gpa: Double(3.0),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )

Condiciones de query

Puedes usar $jsonSchema en condiciones de query para operaciones de lectura y guardar para encontrar documentos en la colección que cumplan con el esquema especificado.

Por ejemplo, crea una colección de muestra inventory con los siguientes documentos:

db.inventory.insertMany( [
   { item: "journal", qty: NumberInt(25), size: { h: 14, w: 21, uom: "cm" }, instock: true },
   { item: "notebook", qty: NumberInt(50), size: { h: 8.5, w: 11, uom: "in" }, instock: true },
   { item: "paper", qty: NumberInt(100), size: { h: 8.5, w: 11, uom: "in" }, instock: 1 },
   { item: "planner", qty: NumberInt(75), size: { h: 22.85, w: 30, uom: "cm" }, instock: 1 },
   { item: "postcard", qty: NumberInt(45), size: { h: 10, w: 15.25, uom: "cm" }, instock: true },
   { item: "apple", qty: NumberInt(45), status: "A", instock: true },
   { item: "pears", qty: NumberInt(50), status: "A", instock: true }
] )

A continuación, defina el siguiente objeto de esquema de muestra:

let myschema =  {
      required: [ "item", "qty", "instock" ],
      properties: {
         item: { bsonType: "string" },
         qty: { bsonType: "int" },
         size: {
            bsonType: "object",
            required: [ "uom" ],
            properties: {
               uom: { bsonType: "string" },
               h: { bsonType: "double" },
               w: { bsonType: "double" }
            }
          },
          instock: { bsonType: "bool" }
      }
 }

Puede utilizar $jsonSchema para encontrar todos los documentos en la colección que cumplan con el esquema:

db.inventory.find( { $jsonSchema: myschema } )
db.inventory.aggregate( [ { $match: { $jsonSchema: myschema } } ] )

Puedes usar $jsonSchema con el $nor para encontrar todos los documentos que no cumplen con el esquema:

db.inventory.find( { $nor: [ { $jsonSchema: myschema } ] } )

O bien, puedes actualizar todos los documentos que no satisfagan el esquema:

db.inventory.updateMany( { $nor: [ { $jsonSchema: myschema } ] }, { $set: { isValid: false } } )

O bien, puede eliminar todos los documentos que no cumplan con el esquema:

db.inventory.deleteMany( { $nor: [ { $jsonSchema: myschema } ] } )

JSON Schema

Para obtener más información sobre JSON Schema, consulta el sitio web oficial.

Palabras clave disponibles

Nota

MongoDB implementa un subconjunto de palabras clave disponibles en JSON Schema. Para una lista completa de omisiones, consulta Omisiones.

Keyword	Tipo	Definición	Comportamiento
bsonType	todo tipo	string alias o arreglo de alias de string	Acepta los mismos alias de string utilizados para el operador `$type`
enum	todo tipo	arreglo de valores	Enumera todos los valores posibles del campo
tipo	todo tipo	string o arreglo de cadenas únicas	Enumera los posibles tipos JSON del campo. Los tipos disponibles son "objeto", "arreglo", "número", "booleano", "string" y "nulo". La implementación de MongoDB del esquema JSON no admite el tipo "entero". Utilza la palabra clave `bsonType` y los tipos "int" o "long" en su lugar.
allOf	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir con todos los esquemas especificados
anyOf	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir con al menos uno de los esquemas especificados
uno de	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir exactamente con uno de los esquemas especificados
no	todo tipo	un objeto de JSON Schema	El campo no debe coincidir con el esquema
múltipleDe	números	Número	El campo debe ser un múltiplo de este valor
máximo	números	Número	Indica el valor máximo del campo
exclusivoMáximo	números	booleano	Si es verdadero y el campo es un número, `maximum` es un máximo exclusivo. De lo contrario, es un máximo inclusivo.
mínimo	números	Número	Indica el valor mínimo del campo
exclusiveMinimum	números	booleano	Si es verdadero, `minimum` es un valor mínimo exclusivo. En caso contrario, se trata de un mínimo inclusivo.
longitud máxima	Cuerdas	entero	Indica la longitud máxima del campo
minLength	Cuerdas	entero	Indica la longitud mínima del campo
Patrón	Cuerdas	cadena que contiene una expresión regular	El campo debe coincidir con la expresión regular
maxProperties	objeto	entero	Indica el número máximo de propiedades del campo.
minPropiedades	objeto	entero	Indica el número mínimo de propiedades del campo
Requerido	objeto	matriz de cadenas únicas	El conjunto de propiedades del objeto debe contener todos los elementos especificados en el arreglo
Propiedades adicionales	objeto	Booleano o objeto	Si `true`, están permitidos campos adicionales. Si `false`, no lo son. Si se especifica un objeto JSON Schema válido, los campos adicionales deben validarse según el esquema. Se establece por defecto en `true`.
Propiedades	objeto	Objeto	Un esquema JSON válido donde cada valor también sea un objeto JSON Schema válido
patternProperties	objeto	Objeto	Además de los requisitos `properties`, cada nombre de propiedad de este objeto debe ser una expresión regular válida
dependencies	objeto	Objeto	Describe las dependencias de campos o esquemas
itemsAdicionales	Arreglos	Booleano o objeto	Si es un objeto, debe ser un JSON Schema válido
elementos	Arreglos	objeto o matriz	Debe ser un JSON Schema válido o un arreglo de JSON Schemas válidos.
maxItems	Arreglos	entero	Indica la longitud máxima del arreglo
minÍtems	Arreglos	entero	Indica la longitud mínima del arreglo
Artículos únicos	Arreglos	booleano	Si es verdadero, cada elemento del arreglo debe ser único. De lo contrario, no se aplica ninguna restricción de unicidad.
Título	N/A	string	Una string de título descriptiva sin efecto.
Descripción	N/A	string	Una cadena que describe el esquema y no tiene ningún efecto.

Extensiones

La implementación del esquema JSON de MongoDB incluye la adición de la bsonType palabra clave, que le permite utilizar todos los tipos BSON en el $jsonSchema operador. bsonType acepta los mismos alias de cadena utilizados para el $type operador.

Omisiones

Los siguientes no son compatibles con la implementación del esquema JSON de MongoDB:

Definiciones de hipervínculo en el borrador 4 de la especificación JSON Schema.
Las palabras clave:
- $ref
- $schema
- default
- definitions
- format
- id
El integer tipo. Debe utilizar el tipo BSON int o long con la bsonType palabra clave.
Propiedades de hipermedia y vinculación del esquema JSON, incluido el uso de referencias JSON y punteros JSON.
Palabras clave desconocidas.

Volver

$expr

$mod