$jsonSchema

  • Se aplica a: ✅ Azure DocumentDB

El $jsonSchema operador se usa para validar documentos con una especificación de esquema JSON. Garantiza que los documentos se ajusten a una estructura predefinida, tipos de datos y reglas de validación.

Syntax

La sintaxis del $objectToArray operador es la siguiente:

db.createCollection("collectionName", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["field1", "field2"],
      properties: {
        field1: {
          bsonType: "string",
          description: "Description of field1 requirements"
        },
        field2: {
          bsonType: "int",
          minimum: 0,
          description: "Description of field2 requirements"
        }
      }
    }
  },
  validationLevel: "strict", // Optional: "strict" or "moderate"
  validationAction: "error"   // Optional: "error" or "warn"
})

Parámetros

Parámetro Description
bsonType Especifica los tipos JSON binarios (BSON) que el campo debe coincidir. Acepta alias de cadena utilizados por el operador $type.
properties Objeto que define reglas de validación para campos específicos.
minimum/maximum Restricciones numéricas para campos numéricos.
minLength/maxLength Restricciones de longitud de cadena.
minItems/maxItems Restricciones de longitud de matriz.
pattern Patrón de expresión regular para la validación de cadenas.
items Validación del esquema para los elementos de matriz.
uniqueItems Boolean que indica si los elementos de matriz deben ser únicos.

Palabras clave admitidas

DocumentDB admite las siguientes palabras clave de esquema JSON:

Keyword Tipo Description Usage
additionalItems arrays Esquema para elementos de matriz adicionales Validación de matriz extendida
bsonType Todos los tipos Extensión de MongoDB: acepta alias de tipo BSON "string", "int", "double", "object", "array", , "bool""date"
exclusiveMinimum Números Límite mínimo exclusivo Validación numérica avanzada
exclusiveMaximum Números Límite máximo exclusivo Validación numérica avanzada
items arrays Esquema para elementos de matriz Validación de elementos de matriz
minimum Números Restricción de valor mínimo Validación numérica
maximum Números Restricción de valor máximo Validación numérica
minItems arrays Longitud mínima de la matriz Validación del tamaño de matriz
maxItems arrays Longitud máxima de la matriz Validación del tamaño de matriz
multipleOf Números El valor debe ser múltiplo del número especificado. Restricciones matemáticas
minLength cuerdas Longitud mínima de cadena Validación de cadenas
maxLength cuerdas Longitud máxima de cadena Validación de cadenas
pattern cuerdas Coincidencia de patrones de expresión regular Validación de formato de cadena
properties Objetos Definición de reglas de validación para campos de objeto Definición de esquema para objetos anidados
required Objetos Matriz de nombres de campo necesarios Exigir campos obligatorios
type Todos los tipos Tipos de esquema JSON estándar "object", "array", "number", "boolean", , "string", "null"
uniqueItems arrays Exigir elementos de matriz únicos Integridad de datos

Palabras clave no admitidas

Estas palabras clave de esquema JSON todavía se admiten en DocumentDB:

Keyword Tipo Motivo de no compatibilidad Solución
additionalProperties Objetos No implementado Uso de definiciones explícitas properties
allOf Todos los tipos Operador lógico no admitido Uso de la validación anidada
anyOf Todos los tipos Operador lógico no admitido Utilice consultas separadas
dependencies Objetos No se admite la validación de dependencias complejas Identificador en la lógica de la aplicación
description N/A Es posible que no aparezca en los mensajes de error Solo informativo
enum Todos los tipos No se admite la validación de enumeración Use $in el operador en su lugar
maxProperties Objetos No se admite la validación del recuento de propiedades Identificador en la lógica de la aplicación
minProperties Objetos No se admite la validación del recuento de propiedades Identificador en la lógica de la aplicación
not Todos los tipos Operador de negación no admitido Uso de reglas de validación positivas
oneOf Todos los tipos Operador lógico no admitido Uso de la validación de nivel de aplicación
patternProperties Objetos No se admite la validación de propiedades basada en patrones Usar nombres de propiedad explícitos
title N/A Campo de metadatos no procesado Use description en su lugar

Examples

Vamos a explorar ejemplos prácticos mediante el stores conjunto de datos:

{
  "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
  "name": "First Up Consultants | Bed and Bath Center - South Amir",
  "location": {
    "lat": 60.7954,
    "lon": -142.0012
  },
  "staff": {
    "totalStaff": {
      "fullTime": 18,
      "partTime": 17
    }
  },
  "sales": {
    "totalSales": 37701,
    "salesByCategory": [
      {
        "categoryName": "Mattress Toppers",
        "totalSales": 37701
      }
    ]
  }
}

Ejemplo 1: Validación básica de la estructura

Esta consulta recupera todos los almacenes con nombres entre 5 y 100 caracteres, y que las coordenadas geográficas se encuentran dentro de intervalos válidos: latitud entre -90 y 90, y longitud entre -180 y 180.

db.stores.find({
  $jsonSchema: {
    bsonType: "object",
    properties: {
      _id: {
        bsonType: "string"
      },
      name: {
        bsonType: "string",
        minLength: 5,
        maxLength: 100
      },
      location: {
        bsonType: "object",
        properties: {
          lat: {
            bsonType: "double",
            minimum: -90,
            maximum: 90
          },
          lon: {
            bsonType: "double",
            minimum: -180,
            maximum: 180
          }
        }
      }
    }
  }
}).limit(1)

Ejemplo 2: Validación de ventas con elementos de matriz

Esta consulta recupera todos los documentos de almacén en los que el campo sales es un objeto válido que contiene un valor totalSales no negativo y una matriz salesByCategory con al menos un elemento.

db.stores.find({
  $jsonSchema: {
    bsonType: "object",
    properties: {
      sales: {
        bsonType: "object",
        properties: {
          totalSales: {
            bsonType: "int",
            minimum: 0
          },
          salesByCategory: {
            bsonType: "array",
            minItems: 1,
            items: {
              bsonType: "object",
              properties: {
                categoryName: {
                  bsonType: "string",
                  minLength: 1
                },
                totalSales: {
                  bsonType: "int",
                  minimum: 0
                }
              }
            }
          }
        }
      }
    }
  }
}).limit(1)

Esta consulta debe devolver esta salida:

[
  {
    _id: 'new-store-001',
    name: 'Adatum Corporation - Downtown Branch',
    sales: { totalSales: 5000 },
    createdDate: ISODate('2025-06-11T11:11:32.262Z'),
    status: 'new',
    staff: { totalStaff: { fullTime: 0, partTime: 0 } },
    version: 1,
    storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'),
    storeFeatures: 213
  }
]

Ejemplo 3: Combinación con operadores de consulta

Esta consulta recupera todos los documentos de almacén en los que el campo personal es un objeto válido que incluye un subobjeto totalStaff con al menos un miembro del personal de tiempo completo (fullTime ≥ 1) y sales.totalSales mayores que 10 000.

db.stores.find({
  $and: [
    {
      $jsonSchema: {
        properties: {
          staff: {
            bsonType: "object",
            properties: {
              totalStaff: {
                bsonType: "object",
                properties: {
                  fullTime: {
                    bsonType: "int",
                    minimum: 1
                  }
                }
              }
            }
          }
        }
      }
    },
    // Additional query constraints
    {
      "sales.totalSales": { $gt: 10000 }
    }
  ]
}).limit(1)

Esta consulta devuelve el siguiente resultado:

[
  {
    _id: 'future-electronics-001',
    address: { city: 'New Tech City' },
    name: 'Boulder Innovations - Future Electronics Hub',
    sales: { totalSales: 25000 },
    establishedDate: ISODate('2025-06-11T11:14:23.147Z'),
    categories: [ 'electronics', 'gadgets', 'smart-home' ],
    promotionEvents: [],
    ratings: { average: 0, count: 0, reviews: [] },
    inventory: {
      lastUpdated: ISODate('2025-06-11T11:14:23.147Z'),
      totalItems: 0,
      lowStockAlerts: []
    },
    storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'),
    storeFeatures: 120
  }
]
  • Last updated on