Concepto y contexto
JSON Schema es un lenguaje declarativo para describir la forma esperada de datos JSON y comprobar si una instancia cumple ese contrato.
Separa la sintaxis JSON válida de los requisitos estructurales y semánticos que una aplicación desea imponer.
Un buen modelo mental separa el concepto abstracto de su representación concreta y del entorno donde se utiliza. Esa separación evita trasladar automáticamente supuestos válidos en un protocolo, biblioteca o formato hacia sistemas que pueden aplicar reglas o garantías diferentes.
Fundamentos y terminología
Un esquema usa palabras clave como type, properties, required, items, enum, pattern y restricciones numéricas para describir valores permitidos.
$id y $ref permiten identificar y reutilizar definiciones, mientras que el draft elegido fija la semántica exacta de cada keyword.
La terminología debe leerse junto con el estándar, versión o contrato que la define, porque palabras parecidas pueden describir propiedades distintas según la capa. Explicitar esas definiciones mejora interoperabilidad, documentación y capacidad para diagnosticar comportamientos inesperados.
Cómo funciona
La validación compara una instancia con el esquema e informa de las restricciones incumplidas.
allOf, anyOf, oneOf y not permiten componer modelos complejos, aunque las alternativas solapadas deben diseñarse con cuidado para evitar resultados inesperados.
En sistemas reales conviene seguir el recorrido de los datos entre capas e identificar qué transformaciones son reversibles, cuáles introducen restricciones y dónde puede perderse información. Así resulta más sencillo razonar sobre responsabilidades entre productores, consumidores, almacenamiento y transporte.
Ejemplo razonado
Un objeto de usuario puede exigir name como cadena no vacía, age como entero no negativo y role dentro de una enumeración.
El JSON puede ser sintácticamente correcto y aun así fallar porque falta una propiedad requerida o un valor queda fuera del dominio declarado.
Un ejemplo razonado es reutilizable cuando muestra sus precondiciones e invariantes y no solo el resultado final. Cambiar un supuesto cada vez permite distinguir el comportamiento garantizado por un estándar de las decisiones particulares de una aplicación o implementación.
Errores y conceptos equivocados
JSON Schema no sustituye reglas de negocio que dependen de bases de datos, autorización o estado del sistema.
También es un error considerar default una transformación universal: normalmente es una anotación salvo que un consumidor decida materializarla.
Muchos fallos nacen de supuestos implícitos entre sistemas aparentemente compatibles que usan versiones, reglas de canonicalización o modelos de tipos diferentes. En interoperabilidad y seguridad conviene especificar y probar entradas anómalas en lugar de tratarlas como casos irrelevantes.
Buenas prácticas y criterios de elección
Mantén esquemas modulares, versionados y acompañados de ejemplos válidos e inválidos representativos.
Al evolucionar contratos evalúa compatibilidad backward y forward, diferencia campos opcionales de nullable y define una política explícita para propiedades desconocidas.
Una práctica robusta combina estándares documentados, bibliotecas maduras, contratos explícitos y pruebas con casos límite representativos. La mejor elección no es siempre la más breve o popular: también cuentan portabilidad, legibilidad, rendimiento, seguridad, evolución y coste operativo.
