/ /

Validación de esquema

Docs Home

/ /

Mejores prácticas

Validación de esquema

Validación de esquema

Especificar la validación para colecciones polimórficas

Puede especificar la validación del esquema para una colección que almacena datos polimórficos o documentos con estructuras o esquemas variables.

Para crear la validación de esquemas para múltiples esquemas dentro de una única colección, puedes configurar los esquemas en tus reglas de validación y asegurarte de que los documentos se ajusten a uno de los esquemas de tu colección.

Acerca de esta tarea

Considere una colección, accountsque almacena datos sobre los clientes de un banco y sus detalles de cuenta. La colección contiene tanto customer documentos como account documentos.

El siguiente código inserta dos documentos customer en la colección accounts para almacenar los datos de los clientes Andrew y Anne, respectivamente. También inserta dos documentos account para representar cada una de sus cuentas de ahorro individuales y un tercer documento account para representar su cuenta corriente compartida. Puede ejecutar el código de este tutorial en Shell de MongoDB (mongosh).

db.accounts.insertMany( [
   {
      "customerId": "CUST-123456789",
      "docType": "customer",
      "name": {
         "title": "Mr",
         "first": "Andrew",
         "middle": "James",
         "last": "Morgan"
      },
      "address": {
         "street1": "240 Blackfriars Rd",
         "city": "London",
         "postCode": "SE1 8NW",
         "country": "UK"
      },
      "customerSince": ISODate("2005-05-20")
   },
   {
      "customerId": "CUST-987654321",
      "docType": "customer",
      "name": {
         "title": "Mrs",
         "first": "Anne",
         "last": "Morgan"
      },
      "address": {
         "street1": "240 Blackfriars Rd",
         "city": "London",
         "postCode": "SE1 8NW",
         "country": "UK"
      },
      "customerSince": ISODate("2003-12-01")
   },
   {
      "accountNumber": "ACC1000000654",
      "docType": "account",
      "accountType": "checking",
      "customerId": [
         "CUST-123456789",
         "CUST-987654321"
      ],
      "dateOpened": ISODate("2003-12-01"),
      "balance": Decimal128("5067.65")
   },
   {
      "accountNumber": "ACC1000000432",
      "docType": "account",
      "accountType": "savings",
      "customerId": [
         "CUST-123456789"
      ],
      "dateOpened": ISODate("2005-10-28"),
      "balance": Decimal128("10341.21")
   },
   {
      "accountNumber": "ACC1000000890",
      "docType": "account",
      "accountType": "savings",
      "customerId": [
         "CUST-987654321"
      ],
      "dateOpened": ISODate("2003-12-15"),
      "balance": Decimal128("10341.89")
   }
] );

Para permitir únicamente documentos que cumplan con los esquemas customer o account en la colección accounts, configure la validación del esquema utilizando el siguiente procedimiento.

Pasos

Crea una definición de esquema JSON para cada tipo de documento

Para distinguir entre diferentes tipos de documentos, puede usar varios esquemas JSON. Para definir qué atributos deben estar en un documento y qué tipos de datos aceptan, cree dos esquemas: uno para un documento customer y otro para un documento account. Cada esquema incluye un atributo docType para identificar el tipo de entidad que representa.

const customerSchema = {
   required: ["docType", "customerId", "name", "customerSince"],
   properties: {
      docType: { enum: ["customer"] },
      customerId: { bsonType: "string"},
      name: {
            bsonType: "object",
            required: ["first", "last"],
            properties: {
               title: { enum: ["Mr", "Mrs", "Ms", "Dr"]},
               first: { bsonType: "string" },
               middle: { bsonType: "string" },
               last: { bsonType: "string" }
            }
      },
      address: {
            bsonType: "object",
            required: ["street1", "city", "postCode", "country"],
            properties: {
               street1: { bsonType: "string" },
               street2: { bsonType: "string" },
               postCode: { bsonType: "string" },
               country: { bsonType: "string" }
            }
      },
      customerSince: {
            bsonType: "date"
      }
   }
};
const accountSchema = {
   required: ["docType", "accountNumber", "accountType", "customerId", "dateOpened", "balance"],
   properties: {
      docType: { enum: ["account"] },
      accountNumber: { bsonType: "string" },
      accountType: { enum: ["checking", "savings", "mortgage", "loan"] },
      customerId: { bsonType: "array" },
      dateOpened: { bsonType: "date" },
      balance: { bsonType: "decimal" }
   }
};

Configurar la colección para aceptar solo los documentos apropiados

Para permitir documentos que coincidan con el customerSchema o el accountSchema, utiliza el operador de esquema JSON oneOf. Luego, use el comando collMod para actualizar la colección accounts que se utilizará en su validación del esquema.

db.runCommand({
   collMod: "accounts",
   validator: { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] } }
})

Agregar validaciones semánticas adicionales

Opcionalmente, puedes añadir validaciones semánticas adicionales. Por ejemplo, puedes añadir las siguientes restricciones a los documentos de tu colección:

Para los documentos customer, el valor customerSince no puede ser anterior a la hora actual.
Para los documentos account, el valor dateOpened no puede ser anterior a la hora actual.
Para las cuentas de ahorro, el balance no puede caer por debajo de cero.

Se pueden implementar las validaciones extra identificando documentos customer y account no válidos e implementando esas restricciones en la validación del esquema.

const invalidCustomer = {
   "$expr": { "$gt": ["$customerSince", "$$NOW"] }
};
const invalidAccount = {
   $or: [
      {
            accountType: "savings",
            balance: { $lt: 0}
      },
      {
            "$expr": { "$gt": ["$dateOpened", "$$NOW"]}
      }
   ]
};

const schemaValidation = {
   "$and": [
      { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }},
      { $nor: [
            invalidCustomer,
            invalidAccount
         ]
      }
   ]
};
db.runCommand({
   collMod: "accounts",
   validator: schemaValidation
})

Verifique los documentos en su colección

Para verificar que todos los documentos que ya están en tu colección cumplan con tu nueva validación de esquema, usa el comando db.collection.validate().

db.accounts.validate()

{
   ns: '66cf8508e64dbb03ce45b30e_test.accounts',
   uuid: UUID('1aedf62a-f202-4e7c-b434-879057bb6d6b'),
   nInvalidDocuments: 0,
   nNonCompliantDocuments: 0,
   nrecords: 10,
   nIndexes: 1,
   keysPerIndex: { _id_: 10 },
   indexDetails: { _id_: { valid: true } },
   valid: true,
   repaired: false,
   readTimestamp: Timestamp({ t: 1749235730, i: 26 }),
   warnings: [],
   errors: [],
   extraIndexEntries: [],
   missingIndexEntries: [],
   corruptRecords: [],
   ok: 1,
   '$clusterTime': {
      clusterTime: Timestamp({ t: 1749235753, i: 31 }),
      signature: {
         hash: Binary.createFromBase64('3h7qyhLsgU21Pnzf/KVLl8suu2I=', 0),
         keyId: Long('7449048397505364002')
      }
   },
   operationTime: Timestamp({ t: 1749235753, i: 31 })
}

nNonCompliantDocuments: 0 en la salida indica que todos los documentos de la colección accounts cumplen con los esquemas de la colección.

Pruebe la validación de su esquema

Para verificar la validación de esquema, puedes probar a insertar un documento no válido en la colección accounts. Por ejemplo, intenta insertar un documento de customer sin el campo obligatorio last, para el apellido:

db.accounts.insertOne(
   {
      "docType": "customer",
      "customerId": "12345",
      "name": {
         "first": "John",
      },
      "customerSince": "2025-01-01T00:00:00Z"
   }
)

MongoServerError: Document failed validation

Volver

Realizar una query y modificar

Diseñando su esquema