UP | HOME

JSON Schema: el enfoque moderno

Índice

Los documentos XML validados por medio de XSD introducen una complejidad derivada del hecho de andar gestionando rutas de esquemas, espacios de nombres y validaciones XML tan pesadas, que ha llevado a la industria del software a virar hacia el uso de JSON Schema.

En este apartado nos vamos a meter de lleno en JSON Schema.

Introducción a JSON Schema

En el apartado anterior vimos que los documentos XML se validan mediante XSD (XML Schema Definition). Sin embargo, en el desarrollo actual de software, centrado en APIs REST, microservicios, bases de datos NoSQL y ficheros de configuración, el formato rey para el intercambio de datos es *JSON (JavaScript Object Notation).

Al igual que ocurría con XML, cuando una aplicación recibe un JSON del exterior, necesita asegurarse de que los datos tienen la estructura correcta, los campos obligatorios y los tipos de datos adecuados (por ejemplo, que una edad sea un número y no una letra). Para resolver esta necesidad nació JSON Schema.

JSON Schema es un estándar basado en el propio formato JSON que permite definir un "contrato de datos" o esquema de validación.

En otras palabras: JSON Schema es el equivalente moderno a los esquemas XSD, pero adaptado de forma nativa a la sintaxis de JSON.

Estructura básica de un JSON Schema por medio de un ejemplo

Para ver cómo funciona, imagina que queremos validar un objeto JSON muy sencillo (producto.json) que representa un producto.

El documento JSON de datos que envía el cliente sería así:

{
  "id": "P001",
  "nombre": "Teclado mecánico",
  "precio": 45.99,
  "enStock": true
}

Y su correspondiente JSON Schema para validarlo (producto.schema.json) sería el siguiente:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Producto",
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "nombre": { "type": "string" },
    "precio": { "type": "number" },
    "enStock": { "type": "boolean" }
  },
  "required": ["id", "nombre", "precio"]
}

Como puedes observar, la lógica es idéntica a la que ya conocemos:

  1. Indicamos qué versión del estándar usamos con $schema.
  2. Definimos que la raíz es un objeto (type: "object").
  3. Listamos las propiedades y sus tipos (string, number, boolean) dentro de properties.
  4. Especificamos qué campos son obligatorios mediante el array required.

Tipos de datos y propiedades principales en JSON Schema

A diferencia de XSD, donde teníamos una lista kilométrica de tipos de datos ultra específicos (como xs:unsignedByte, xs:gYear, etc), JSON Schema es mucho más minimalista y directo. Hereda de forma natural los tipos primitivos que ya conocemos de JSON.

Los tipos de datos que podemos validar con la propiedad type son:

  • string: cadenas de texto.
  • number: números (tanto enteros como decimales).
  • integer: números exclusivamente enteros.
  • boolean: valores lógicos (true o false).
  • array: listas o vectores de elementos.
  • object: estructuras anidadas con propiedades clave-valor.
  • null: valores nulos.

Controlando los objetos y las propiedades

Cuando definimos un objeto (type: "object"), la validación gira en torno a tres herramientas fundamentales que utilizaremos constantemente:

  • properties: define qué campos (propiedades) están permitidos dentro del objeto y qué reglas cumple cada uno.
  • required: un array con los nombres de los campos que son obligatorios. Si falta alguno, el validador dará error.
  • additionalProperties: controla qué ocurre si el documento JSON incluye campos que no han sido declarados en properties:
    • Si se fija a false, el validador rechaza cualquier campo extra no invitado (muy útil para evitar erratas o datos basura).
    • Si se omite o se pone a true, se permiten campos adicionales.

Ejemplo práctico: en el que se define un objeto llamado Usuario con tres propiedades dos de los cuales son obligatorios y no se permiten propiedades diferentes a estas tres:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Usuario",
  "type": "object",
  "properties": {
    "nombre": { "type": "string" },
    "edad": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["nombre", "email"],
  "additionalProperties": false
}

Trabajando con listas (o arrays)

En JSON, un array se utiliza para representar listas de elementos (por ejemplo, una lista de aficiones, un listado de productos en un carrito, o una lista de usuarios).

Cuando validamos un array en JSON Schema, necesitamos especificar principalmente dos cosas: asegurar que el tipo es un array y definir qué estructura o reglas deben cumplir los elementos de su interior.

Las propiedades clave para manejar arrays son:

  1. type: "array": indica que la propiedad obligatoriamente debe ser una lista.
  2. items: define el esquema que todos los elementos del array deben cumplir de forma uniforme.
  3. Restricciones de tamaño:
    • minItems: número mínimo de elementos permitidos en la lista.
    • maxItems: número máximo de elementos permitidos.
    • uniqueItems: si se pone a true, obliga a que no haya elementos duplicados en la lista.

Ejemplo: imagina que queremos validar la ficha de un usuario que incluye una lista de aficiones (donde cada afición es obligatoriamente una cadena de texto y debe haber al menos una):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Ficha con aficiones",
  "type": "object",
  "properties": {
    "nombre": { "type": "string" },
    "hobbies": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    }
  },
  "required": ["nombre", "hobbies"]
}

Como ves, la propiedad items anida otro pequeño esquema, { "type": "string" }, que se aplica automáticamente a cada uno de los elementos que formen parte del array.

Arrays de objetos: el pan de cada día en las APIs

Cuando queremos validar una estructura donde la raíz (o una de sus propiedades) es una lista y cada elemento de esa lista es a su vez un objeto complejo, combinamos type: "array" con un esquema de tipo object dentro de la propiedad items.

Ejemplo práctico:

Imagina que queremos validar un listado de personas donde cada persona tiene obligatoriamente un nombre, una edad y un array secundario con sus aficiones.

El esquema JSON Schema (personas.schema.json) sería así:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Listado de personas",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer", "minimum": 0 },
      "hobbies": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["name", "age"],
    "additionalProperties": false
  }
}

Y un documento JSON de datos válido que cumple este esquema sería:

[
  {
    "name": "Alice Smith",
    "age": 30,
    "hobbies": ["reading", "hiking"]
  },
  {
    "name": "Bob Johnson",
    "age": 45,
    "hobbies": ["golf"]
  }
]

Como puedes observar en este patrón:

  • La raíz global es un array (type: "array").
  • La propiedad items define que cada elemento de esa lista debe ser un objeto (type: "object").
  • Dentro de ese objeto se despliegan las propiedades individuales de cada registro con sus respectivas reglas.

Restricciones

En casos concretos, como sucedía con XSD, es necesario aplicar restricciones sobre los valores de las propiedades. Indicando el tipo, simplemente, a veces no es suficiente.

En los siguientes apartados vemos cómo usar restricciones en JSON Schema.

Validando cadenas complejas con expresiones regulares

A veces un campo de texto no es cualquier cosa, sino que debe seguir un formato o patrón muy estricto (por ejemplo, códigos de producto, matrículas, DNI o códigos postales).

En JSON Schema utilizamos la palabra clave pattern, a la cual se le pasa una expresión regular estándar.

Sin más, para entender su uso, aquí tienes un ejemplo:

{
  "id_centro": {
    "type": "string",
    "pattern": "^[A-Z]{3}-[0-9]{3}$"
  }
}

Restricciones sobre cadenas

Para las cadenas de texto, o string, podemos usar las siguiente propiedades:

  • minLength / maxLength: longitud mínima y máxima.
  • format: validación contra formatos comunes:
    • email
    • uri
    • uuid
    • date
    • date-time

Aquí puedes ver un ejemplo con proiedades sobre las que se aplican estas restricciones:

  {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Perfil de Usuario",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 15
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "website": {
      "type": "string",
      "format": "uri"
    },
    "id_unico": {
      "type": "string",
      "format": "uuid"
    },
    "fecha_creacion": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Restringiendo valores numéricos

Para los tipos number o integer, podemos establecer límites estrictos para evitar datos imposibles (como precios negativos o coordenadas geográficas fuera de rango).

Para los tipos number o integer, podemos establecer límites estrictos para evitar datos imposibles (como precios negativos o coordenadas geográficas fuera de rango):

  • minimum: Valor mínimo permitido (inclusive).
  • maximum: Valor máximo permitido (inclusive).
  • exclusiveMinimum / exclusiveMaximum: Para límites exclusivos (estrictamente mayor o menor).

Ejemplo:

{
  "latitud": {
    "type": "number",
    "minimum": -90,
    "maximum": 90
  }
}

Listados de valores permitidos (enumeraciones)

Cuando un campo de texto solo puede tomar una serie de valores exactos y predefinidos, utilizamos la palabra clave enum pasándole un array con las opciones válidas. Por ejemplo:

{
  "categoria": {
    "type": "string",
    "enum": ["alimentacion", "bebidas", "higiene", "tecnologia"]
  }
}

Autor: Román Ginés Martínez Ferrández

Created: 2026-11-10 mar 17:51

Validate