Tipos, propiedades y campos requeridos

La mayoría de esquemas cotidianos empiezan con objetos. Los objetos JSON se convierten en contratos útiles cuando describes sus propiedades y decides qué campos son requeridos.

{
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "profile": {
      "type": "object",
      "properties": {
        "displayName": { "type": "string" }
      },
      "required": ["displayName"]
    }
  },
  "required": ["email", "profile"]
}

type

La palabra clave type puede describir primitivos y contenedores JSON:

• object
• array
• string
• number
• integer
• boolean
• null

Usa integer solo cuando los valores fraccionarios sean inválidos. Usa number para decimales como precios, coordenadas y ratios.

properties

properties mapea nombres de campo a esquemas. Cada propiedad puede tener su propio tipo y restricciones anidadas.

Los objetos anidados deben modelarse deliberadamente. Si un valor anidado tiene campos significativos, dale su propio bloque de esquema en lugar de dejarlo como un object genérico.

required

required es un array de nombres de propiedad que deben estar presentes. Un error común es pensar que toda propiedad listada bajo properties es automáticamente requerida. No lo es.

Esto significa que puedes describir campos opcionales sin forzar a los clientes a enviarlos:

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "subtitle": { "type": "string" }
  },
  "required": ["title"]
}

Requerido no significa no vacío

Una cadena requerida aún puede estar vacía a menos que añadas minLength.

{ "type": "string", "minLength": 1 }

Piensa en requerido como una regla de presencia. Piensa en restricciones como minLength, minimum y pattern como reglas de valor.