Qué resuelve realmente JSON Schema
En resumen: El Schema gobierna la estructura y los tipos, no el significado de negocio. Evita campos ausentes, tipos erróneos y enums fuera de rango, mientras que reglas como un importe mayor que cero se quedan en el código.
En resumen: deja que JSON Schema imponga estructura, tipos, rangos y formatos, mientras las reglas entre campos, las invariantes de negocio y el estado externo se quedan en el código; adóptalo para API públicas y cargas útiles compartidas, no para un servicio interno de cinco campos.
Responde a «¿estos datos tienen la forma correcta?», no a «¿tienen sentido estos datos?».
Lo que hace bien
Completitud estructural. Qué campos deben existir, si se permiten extras (required, additionalProperties).
Tipos. port como número o cadena, tags como array o escalar. Solo esto elimina mucho código defensivo en sistemas multilingües.
Rangos. enum, minimum/maximum, longitud de cadenas y arrays.
Formatos. format para fechas, email, URI y UUID, con validadores que los imponen.
Anidamiento. Cada nivel de objetos y arrays recibe sus propias restricciones, y los errores llevan una ruta precisa.
Documentación. El Schema es el contrato. Cambia un campo y el diff muestra el radio de impacto. También genera tipos y formularios, así que una sola definición alimenta a varios consumidores.
Lo que no puede hacer
Dependencias entre campos. «El fin debe ser posterior al inicio» puede expresarse con if/then/else, pero el resultado es más largo y más difícil de leer que tres líneas de código.
Invariantes de negocio. «El stock no puede ser negativo» depende de estado externo. El Schema ve un solo documento.
Semántica. price: -100 satisface {"type": "number"} a la perfección. Que sea un precio legal queda fuera del conocimiento del Schema.
Un reparto viable
| Capa | Responsable |
|---|---|
| Sintaxis: ¿es JSON válido? | Analizador |
| Estructura: campos, tipos, rangos, formatos | JSON Schema |
| Semántica: entre campos, reglas de negocio, estado externo | Código de la aplicación |
| Seguridad: tamaño, profundidad, tasa | Gateway / middleware |
Si lo metes todo en un solo sitio, el Schema crece hasta cientos de líneas con cinco niveles de if/then. En ese punto, la gente empieza a rodearlo.
Cuándo merece la pena
- API públicas con consumidores desconocidos
- Varios servicios que leen la misma carga útil
- Sistemas dirigidos por configuración donde los errores tipográficos deben fallar rápido
- Generación de tipos o formularios a partir del contrato
Para un servicio interno pequeño con cinco campos y un único frontend, las comprobaciones escritas a mano son más rápidas de mantener. Introducir Schema ahí es trabajo con saldo negativo.
FAQ
¿Cómo decido si debo adoptar JSON Schema?
Pondera los consumidores públicos, que varios servicios lean la misma carga útil y la necesidad de generar tipos o formularios. Para un servicio interno pequeño con cinco campos y un único frontend, las comprobaciones escritas a mano son más rápidas de mantener.
¿Por qué las reglas entre campos deben quedarse en el código?
«El fin debe ser posterior al inicio» puede meterse a la fuerza en if/then/else, pero el resultado es más largo y más difícil de leer que unas pocas líneas de código. El Schema tampoco puede ver el estado externo.
¿Debería el Schema validar el tamaño de la carga útil y la profundidad de anidamiento?
No. El Schema describe la estructura, no el tamaño ni la profundidad; esos límites pertenecen a una capa de gateway o middleware.