JSON Schema: qué es y cómo validar datos de una API

JSON Schema es un vocabulario para describir la estructura y las reglas que debe cumplir un documento JSON. Un esquema puede indicar que un campo es una cadena, que otro es un número y que un objeto debe contener ciertas propiedades. La especificación separa el núcleo que define la estructura del esquema de las palabras clave que expresan validaciones.

También puede servirte: Qué es OpenAPI y para qué sirve al diseñar una API

La diferencia con comprobar sólo si el JSON está bien escrito es práctica. `{'nombre':'Ana'}` puede ser un JSON válido aunque una API espere también un identificador numérico, una fecha o una lista. El esquema convierte esas expectativas en un contrato que una herramienta puede validar de forma repetible.

JSON Schema no decide cómo transportar los datos ni reemplaza la documentación de una API. Describe instancias JSON y permite comunicar qué acepta un servicio. El equipo todavía debe documentar autenticación, permisos, efectos laterales y respuestas de error en el sistema que expone el endpoint.

Un esquema comienza con un `type`, como `object`, `array`, `string`, `number`, `integer`, `boolean` o `null`. Para un objeto se usa `properties` para describir campos y `required` para declarar cuáles deben aparecer. Si una propiedad no está en `required`, su ausencia puede ser válida aunque esté documentada en el esquema.

Las palabras clave pueden combinarse. Una cadena puede exigir `minLength`, coincidir con un `pattern` o pertenecer a un conjunto de valores mediante `enum`. Un número puede tener `minimum` y `maximum`; una lista puede fijar `minItems` y el tipo de sus elementos con `items`. El validador aplica estas reglas sobre la instancia que recibe.

También conviene decidir qué ocurre con propiedades desconocidas. Algunas APIs las aceptan para permitir evolución; otras usan `additionalProperties: false` para rechazar campos no previstos. La decisión depende de compatibilidad y seguridad: cerrar el objeto puede detectar errores, pero exige una estrategia para agregar campos sin romper clientes viejos.

El esquema puede validar el cuerpo de una solicitud antes de ejecutar la lógica de negocio. Si falta un campo obligatorio o el tipo no coincide, el servidor devuelve un error de entrada y evita escribir datos incompletos. La respuesta debe indicar el campo problemático sin revelar secretos ni información interna del validador.

Para una respuesta, el mismo enfoque permite comprobar que el servidor no omitió una propiedad que el contrato promete. Validar ambos sentidos ayuda a detectar cambios accidentales y hace visibles las diferencias entre el código y el contrato publicado. Los esquemas también pueden servir para generar ejemplos, tipos de cliente y documentación, siempre que esas herramientas respeten la versión del vocabulario.

Guardá los esquemas junto al código y versioná los cambios. Agregar una propiedad opcional suele ser compatible; cambiar el tipo, eliminar un campo requerido o estrechar una restricción puede romper consumidores. La compatibilidad debe revisarse con ejemplos de solicitudes reales y no sólo con una prueba de que el archivo sigue siendo JSON válido.

Primero definí qué versión de JSON Schema usás y fijá el dialecto en el documento. Después escribí ejemplos válidos y casos que deben fallar: campo ausente, tipo equivocado, número fuera de rango, valor no permitido y propiedad adicional. Estos ejemplos funcionan como una prueba del contrato y facilitan una revisión de cambios.

No uses el esquema como única barrera de seguridad. La autorización, la autenticación, los límites de tamaño, la protección contra abuso y el tratamiento de datos sensibles están fuera de sus palabras clave. Un campo con el tipo correcto todavía puede contener un valor peligroso para la lógica de la aplicación.

Por último, medí la validación en el punto donde aporta más valor. Validar al borde evita que datos inválidos recorran todo el sistema; validar de nuevo antes de persistir protege contra caminos internos que no pasan por la API. Esta guía de VisteEsto convierte la documentación oficial en una práctica de contrato y revisión, no en una prueba de rendimiento de una biblioteca concreta.