¿Qué es JSON Schema?

JSON Schema es un vocabulario para describir la forma de datos JSON. Un esquema puede decir que un valor debe ser un objeto, que el objeto debe incluir un campo name, que tags debe ser un array de cadenas, o que un identificador debe coincidir con un formato UUID.

El punto no es solo documentación. Un esquema puede usarse en validadores, editores, comprobaciones CI, gateways de API y fixtures de prueba.

Qué describe un esquema

En su forma más simple, un esquema responde tres preguntas:

• ¿Qué tipo JSON está permitido?
• ¿Qué campos pueden o deben existir?
• ¿Qué restricciones se aplican a cada valor?

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "name": { "type": "string" }
  },
  "required": ["id", "name"]
}

Este esquema valida la forma, no la verdad de negocio. Puede requerir id, pero no puede demostrar que el id existe en tu base de datos a menos que tu aplicación realice esa búsqueda.

Dónde ayudan los esquemas

• Payloads de petición y respuesta
• Archivos de configuración
• Colas de mensajes y flujos de eventos
• Fixtures de prueba
• Datos generados por scripts o sistemas de IA

Qué no reemplazan los esquemas

Los esquemas no reemplazan el análisis de JSON, la validación de dominio, las comprobaciones de autorización ni las restricciones de base de datos. Se sitúan en el límite donde JSON crudo se convierte en un valor en el que tu programa está dispuesto a confiar.

Los buenos esquemas son aburridos en el mejor sentido: hacen que los datos inválidos fallen pronto, cerca del límite del sistema, antes de convertirse en una historia de depuración en producción.