La API de la lección anterior tiene un agujero del tamaño de un camión: si alguien envía {"nombre": "", "precioEuros": "carísimo", "stock": -5, "color": "rojo"}, el café se crea. eurosACentimos("carísimo") produce NaN, el stock queda negativo, el campo color se guarda sin que nadie lo haya previsto y a partir de ahí GET /v1/cafes devuelve "precioEuros": null para siempre. Las comprobaciones a mano que fuimos dejando por el camino son incompletas, están repetidas y cada una inventa su propio mensaje. Hoy las sustituimos por esquemas declarativos con Zod y un único middleware validar(esquema, origen) que rechaza la entrada estricta, convierte los tipos de los parámetros de consulta y devuelve todos los fallos a la vez en detalles, con el formato exacto que fijamos en 02-04. Es la lección que convierte la API en algo que se puede exponer a un consumidor que no sea tú mismo.

1. Por qué nunca se confía en la entrada
2. Qué se valida: cuerpo, ruta, consulta y cabeceras
3. Validación manual frente a validación por esquema
4. Primeros pasos con Zod: parse y safeParse
5. Los tipos que necesita Tienda Aroma
6. z.coerce y el problema de los parámetros de consulta
7. Entrada estricta con .strict()
8. Reglas compuestas con refine y superRefine
9. Normalización con transform
10. Un esquema por operación: partial, extend y merge
11. src/esquemas/comunes.js
12. src/esquemas/cafes.js
13. src/esquemas/pedidos.js
14. El middleware validar(esquema, origen)
15. Del ZodError al formato de error del contrato
16. Las rutas con validación
17. Peticiones inválidas y sus respuestas exactas
18. Validación de negocio: por qué vive en el servicio
19. Sanitización, normalización y límite de tamaño
20. Alternativas a Zod y la conexión con OpenAPI

La regla es tan vieja como el desarrollo web y no admite matices: todo lo que llega por la red es hostil hasta que se demuestre lo contrario. No porque todos los consumidores sean maliciosos —la SPA de Tienda Aroma no lo es—, sino porque:

Ese último punto es el decisivo. La validación del cliente es usabilidad; la validación del servidor es corrección. La primera existe para no hacer esperar al usuario a que el servidor le diga que el campo está vacío; la segunda es la única que protege de verdad los datos, porque la API es pública y nadie está obligado a usar tu SPA para llamarla.

Las consecuencias de no validar se dividen en dos familias:

• Integridad. Datos corruptos que se propagan: un NaN guardado hoy rompe una factura dentro de tres meses, y para entonces el origen del problema es imposible de rastrear. Además contaminan los cálculos agregados: un precio nulo hace que el informe de ventas mienta.
• Seguridad. Inyección SQL, inyección NoSQL, contaminación de prototipos, denegación de servicio con cuerpos gigantes o expresiones regulares patológicas. Aquí solo veremos cómo la validación cierra la puerta de entrada; el catálogo completo de amenazas y sus defensas es la lección 04-02.

Un principio que ordena todo lo demás: valida en el borde, confía dentro. Una vez que la petición ha pasado el middleware de validación, el resto del código —controlador, servicio, repositorio— puede dar por hecho que datos.precioEuros es un número positivo con dos decimales. Si cada capa vuelve a comprobarlo, el código se llena de defensa inútil y nadie sabe quién es responsable de qué.

Un error frecuente es validar solo el cuerpo. Hay cuatro entradas y las cuatro son igual de manipulables:

En Tienda Aroma validaremos las tres primeras con esquemas. Las cabeceras se comprueban de forma puntual, porque su semántica es del protocolo y no del dominio: el Content-Type de PATCH ya se comprueba en el controlador (03-03) y la Idempotency-Key obligatoria en POST /v1/pedidos se comprobará en un middleware propio.

Así es como quedó la comprobación manual de POST /v1/cafes en 03-03, y solo cubría los campos obligatorios:

Para cubrir el contrato completo habría que añadir: que nombre sea cadena no vacía de longitud razonable, que tueste sea uno de tres valores, que precioEuros sea número positivo con dos decimales, que stock sea entero no negativo, que notasCata sea un array de cadenas, que no haya campos desconocidos… y repetirlo en PUT, y en PATCH con todo opcional, y otra vez para pedidos. Serían doscientas líneas de if que hay que mantener sincronizadas con la documentación.

Un esquema declarativo dice qué debe cumplirse, no cómo comprobarlo. Y como es un objeto, se puede transformar: de un esquema Zod salen un validador, los tipos de TypeScript y un JSON Schema para OpenAPI. De un if no sale nada.

Zod ya está instalado desde 03-01. Los ejemplos usan la API estable, común a las versiones 3 y 4.

En Tienda Aroma usaremos safeParse, porque un cuerpo inválido no es una excepción: es el caso normal de un cliente que se equivoca, y su respuesta es un 400 bien formado, no un error de programa.

Lo esencial del objeto error: la propiedad issues es un array con todos los problemas encontrados, no solo el primero. Cada issue tiene:

Ese issues completo es justo lo que necesita el contrato: la validación devuelve todos los fallos a la vez (02-04), para que el consumidor corrija su petición de una vez y no en cinco intentos.

Un recorrido por los constructores que usaremos, cada uno con su caso real:

Merece una parada el caso de precioEuros. El contrato de 02-05 dice "euros con dos decimales por fuera, céntimos por dentro". Zod no tiene un tipo "decimal con dos cifras", así que se compone:

Una forma más legible y robusta de expresar lo mismo, evitando el ruido de la coma flotante, es comprobar la representación textual:

Así 14.5 y 14.50 pasan (son el mismo número), y 14.567 se rechaza con 400. Aceptar tres decimales sería aceptar fracciones de céntimo que se perderían al convertir, y con ellas la cuadratura contable.

Como vimos en 03-03, todo lo que llega en la URL es texto. ?limite=20&disponible=true produce { limite: '20', disponible: 'true' }. Un z.number() sobre '20' falla, y con razón.

z.coerce convierte antes de validar:

Cuidado con z.coerce.boolean(): aplica la conversión de JavaScript, donde cualquier cadena no vacía es verdadera. Así, ?disponible=false se convertiría en true, que es exactamente el bug que corregimos en el ejercicio 1 de 03-03. Para booleanos en la URL hay que ser explícito:

Esta es la clase de detalle que separa una API que parece funcionar de una que funciona.

Por defecto, z.object() descarta en silencio las claves que no están en el esquema. El contrato de 02-05 decidió lo contrario: entrada estricta, campo desconocido → 400.

Las tres razones de la decisión, que conviene tener a mano porque el debate reaparece siempre:

1. Detecta erratas del cliente. Quien envía precioEuro (sin s) con la versión laxa recibe un 201 alegre y un café con precio por defecto. Con la estricta, recibe un 400 que le dice exactamente qué campo no existe.
2. Impide la asignación masiva. Si mañana el modelo interno tuviera un campo destacado o rolCliente, un cuerpo que lo incluyera podría acabar guardándolo si el código hace {...datos}. La entrada estricta cierra esa puerta desde el borde.
3. Hace explícita la evolución. Añadir un campo a la API pasa a ser una decisión consciente que se refleja en el esquema y en openapi.yaml.

La contrapartida honesta: la entrada estricta reduce la tolerancia. Un cliente que reenvía tal cual una representación que le devolvimos —incluidos _links o fechaCreacion— recibirá un 400. Es un caso real y frecuente en PUT. Se resuelve documentándolo con claridad y, si hace falta, ignorando explícitamente los campos de solo lectura en el esquema en lugar de rechazarlos.

Hay reglas que no son de un campo sino de la relación entre varios. refine añade una comprobación arbitraria:

El path importa: sin él, el fallo no se asocia a ningún campo y el detalles del error queda sin campo.

superRefine permite emitir varios problemas y elegir su código:

Dónde está el límite. En el esquema van las reglas que se pueden comprobar mirando solo la petición: formatos, rangos, coherencia entre campos. Todo lo que necesite consultar el estado del sistema —¿existe ese café?, ¿hay stock?, ¿este pedido ya está pagado?— no va aquí. Volveremos sobre esto en la sección 18, porque es la confusión más común de esta lección.

transform cambia el valor después de validarlo. Nos sirve para dos cosas:

La segunda tentación es fuerte y hay que resistirla en parte. Si el esquema devolviera precioCentimos, el controlador recibiría un objeto que ya no se parece al contrato público, y la traducción de unidades quedaría repartida entre el esquema y el mapeador. En Tienda Aroma mantenemos la conversión en el servicio (eurosACentimos, 03-03) y usamos transform solo para normalizar: recortar espacios, unificar mayúsculas del origen, eliminar notas de cata duplicadas. Una regla útil: transform limpia lo que el cliente escribió; no traduce entre el mundo público y el interno.

POST, PUT y PATCH no piden lo mismo, así que no comparten esquema; comparten piezas.

Y las herramientas de composición:

Un detalle de orden que cuesta una tarde si se descubre por las malas: .strict() se aplica al final. base.strict().partial() funciona, pero si encadenas extend después de strict, conviene volver a cerrarlo. Por eso en nuestros ficheros el .strict() es siempre la última llamada.

Empezamos por las piezas compartidas, para no repetirlas en cada recurso:

Los default() son importantes: gracias a ellos, el controlador recibe limite y desplazamiento siempre con un número, y desaparecen los req.query.limite === undefined ? 20 : ... de 03-03.

El .strict() del esquema de consulta es el que cumple la promesa de 02-06 de que un parámetro desconocido produce 400. ?limit=20 (en inglés, la errata más frecuente) deja de ser un filtro ignorado en silencio y pasa a ser un error explícito que el integrador ve en su primera prueba.

La nota más importante de este fichero es la de esquemaCrearPedido: el cliente no envía precios. Es un caso perfecto de por qué la validación es también diseño. Aceptar precioEuros en la línea de un pedido sería una vulnerabilidad de negocio de libro; rechazarlo con la entrada estricta la elimina de raíz.

Una sola pieza para las tres entradas:

Tres decisiones de diseño que merecen justificarse:

Por qué se sustituye req[origen]. Después del middleware, req.query.limite es el número 20, no la cadena '20', y req.body.notasCata es [] aunque el cliente no lo enviara. El controlador se queda sin conversiones ni valores por defecto: todo eso ocurrió en el borde. Es la materialización de "valida en el borde, confía dentro".

Por qué se traducen los códigos de Zod. too_small o unrecognized_keys son detalles de implementación de una librería. Si los expusiéramos, actualizar Zod podría cambiar el contrato de nuestra API, y eso es inaceptable (02-07). La traducción nos aísla: cambiar de librería no cambiaría ni un codigo visible.

Por qué no se filtran los mensajes. Los mensajes de Zod son legibles y en muchos casos los hemos escrito nosotros en español dentro del esquema. Los que no —los mensajes por defecto en inglés— se pueden traducir; el ejercicio 3 lo aborda.

Nota sobre Express 5. En Express 4, req.query es una propiedad normal y se puede reasignar. En Express 5 pasó a ser un getter de solo lectura, así que la asignación falla en silencio. La solución portable es guardar el resultado en un campo propio (req.validado = { ...req.validado, [origen]: resultado.data }) y leer de ahí en el controlador. Como este curso usa Express 4, mantenemos la forma directa, que es más legible.

Con lo anterior, una petición con cuatro fallos produce esta respuesta:

Cuatro fallos, una sola respuesta. Esa es la promesa de 02-04, y es lo que separa una API amable de una insufrible: con validación "al primer fallo", el integrador necesitaría cuatro intentos y cuatro despliegues de su cliente para descubrir lo mismo.

Para campos anidados, path.join('.') produce rutas legibles:

Ahora las rutas declaran también el contrato de entrada. src/rutas/cafes.js queda así:

Se lee como una especificación: para cada método y URI, qué se valida y quién lo atiende. Y el controlador adelgaza de forma notable, porque desaparecen todas las comprobaciones manuales:

crear ha pasado de veinte líneas a tres. Eso es el beneficio medible de mover la validación al borde.

Este último caso tiene más miga de la que parece. Un id mal formado ahora produce 400 parametro_invalido y nunca llega al repositorio. La alternativa —dejarlo pasar y devolver 404 cafe_no_encontrado— también sería defendible, pero elegimos el 400 porque distingue "te has equivocado escribiendo el identificador" de "ese café no existe", y además ahorra una consulta a la base de datos por cada petición basura. Con SQL detrás (03-05), esa validación previa es además una capa más frente a la inyección.

Hay reglas que un esquema no puede comprobar, y confundirlas con la validación de formato es el error conceptual más común de esta lección:

Las tres razones de fondo:

1. El esquema no tiene acceso a los datos. Meter una consulta dentro de un refine convertiría el esquema en algo asíncrono, dependiente de la base de datos e imposible de reutilizar para generar documentación.
2. El estado cambia. Entre validar "hay stock" y descontarlo puede colarse otro pedido. La comprobación debe ocurrir dentro de la misma transacción que el descuento (03-05); hacerla en el borde da una falsa sensación de seguridad.
3. El código de error es distinto. El formato inválido es 400 datos_invalidos; el stock insuficiente es 409 stock_insuficiente, un conflicto de estado, no un error de escritura. Son familias diferentes en el catálogo de 02-04.

Así queda esa validación en el servicio de pedidos, escrita hoy con la forma provisional que 03-07 convertirá en throw new ErrorApi(...):

Fíjate en que también aquí se acumulan todos los problemas antes de responder. La coherencia con la validación de esquema es deliberada: si un pedido tiene tres líneas sin stock, el cliente merece enterarse de las tres a la vez.

Tres conceptos que se confunden y que hacen cosas distintas:

Tienda Aroma valida y normaliza en el esquema. La sanitización es cuestión de contexto de salida y no se hace aquí: intentar "limpiar" HTML al entrar produce datos mutilados —un cliente que se apellida O'Brien no debería perder el apóstrofo— y una falsa seguridad. Lo correcto es guardar el texto tal cual y escaparlo en el momento de usarlo: parámetros preparados para SQL (03-05), escape de HTML en el cliente que lo pinta. En 04-02 se desarrolla el porqué con detalle.

Sobre el límite de tamaño, ya lo pusimos en 03-02:

Es una defensa que la validación por esquema no puede darte, porque actúa antes: sin límite, un cuerpo de 500 MB se parsea entero en memoria y el proceso muere antes de que Zod vea nada. Con limit, Express responde 413. Ese 413 produce hoy una respuesta fea de Express; en 03-07 lo convertiremos en cuerpo_demasiado_grande del catálogo.

Un último punto: la validación protege contra la contaminación de prototipos. Un cuerpo con {"__proto__": {"esAdmin": true}} podría, combinado con un Object.assign descuidado, modificar el prototipo de todos los objetos del proceso. Con .strict(), esa clave es simplemente un campo desconocido y la petición muere en el borde con un 400.

Esa última fila apunta a un tema importante. En 02-08 escribimos openapi.yaml como fuente de verdad del contrato, y en este módulo hemos escrito esquemas Zod que dicen prácticamente lo mismo. Tenemos dos definiciones de la misma verdad, y dos definiciones acaban divergiendo: alguien añade un campo al esquema Zod y olvida el YAML.

Las tres formas de resolverlo:

1. Generar OpenAPI desde Zod, con herramientas como zod-to-json-schema o @asteasolutions/zod-to-openapi. El código manda.
2. Generar los validadores desde OpenAPI, con AJV y el JSON Schema del contrato. La especificación manda; es lo más coherente con API-first.
3. Mantener las dos y verificar en CI que la implementación cumple la especificación, con pruebas de contrato.

La tercera es la más práctica y la que veremos en 05-04, donde comprobaremos automáticamente que cada respuesta valida contra el esquema publicado. Por ahora basta con ser consciente del riesgo: cada vez que toques un esquema de src/esquemas/, toca también openapi.yaml. Es exactamente la deriva de la que advertíamos en 02-08.

1. Validar solo el cuerpo. Los query params y los parámetros de ruta son igual de manipulables, y ?limite=999999 es un problema de disponibilidad.

2. Usar z.coerce.boolean() para un parámetro de la URL. Convierte cualquier cadena no vacía en true, incluida 'false'. Usa un z.enum(['true','false']).transform(...).

3. Meter consultas a la base de datos en un refine. El esquema no debe conocer el estado del sistema. Esa comprobación pertenece al servicio y a menudo a la misma transacción que la escritura.

4. Devolver los códigos internos de Zod al cliente. too_small es un detalle de una dependencia; si lo publicas, actualizar la librería te obliga a cambiar el contrato.

5. Olvidar .strict(). Sin él, el objeto se valida pero los campos desconocidos se descartan en silencio y el contrato de entrada estricta deja de cumplirse.

6. Reutilizar el esquema de POST para PATCH. PATCH exige todo opcional; usar el de POST obliga al cliente a reenviar el recurso entero, que es lo que hace PUT.

7. Confiar en que el cliente ya valida. Nunca. La SPA valida por usabilidad; el servidor valida por corrección.

8. Validar después de tocar la base de datos. El orden en la cadena de middleware importa: validar va antes del controlador, siempre.

Consejo: cuando dudes de si una comprobación es de esquema o de negocio, pregúntate si podrías responder mirando solo el texto de la petición. Si necesitas consultar algo, es negocio y va en el servicio.

Escribe el esquema esquemaCrearResena para POST /v1/cafes/:id/resenas. Según el contrato: puntuacion es un entero de 1 a 5 obligatorio, comentario es texto opcional de entre 10 y 2000 caracteres, y no se admite ningún otro campo (en particular estado, que lo fija el servidor en pendiente_moderacion). Añade la regla de que si hay comentario, no puede ser solo espacios en blanco. Muestra la ruta con su validación.

Un integrador se queja de que POST /v1/pedidos con este cuerpo devuelve 400 y no entiende por qué:

Enumera todos los fallos que detectará esquemaCrearPedido, escribe la respuesta completa que devuelve la API y explica al integrador por qué el rechazo de precioEuros y totalEuros no es una molestia sino una protección.

Los mensajes por defecto de Zod salen en inglés ("Expected number, received string"), lo que rompe la coherencia de una API cuyos mensajes están en español. Propón una solución que traduzca esos mensajes sin tener que escribir un mensaje a mano en cada campo del esquema, e impleméntala en traducirCodigo/aDetalles. Comenta la ventaja de tener el codigo estable además del mensaje.

Solución 1

El .trim() antes de .min(10) resuelve por sí solo la regla del comentario en blanco: " " se convierte en cadena vacía y falla el mínimo. Es más elegante que un refine, y demuestra que el orden de los encadenamientos en Zod tiene significado.

Sobre estado: no aparece en el esquema a propósito. Con .strict(), un cliente que envíe "estado": "publicada" recibe 400 campo_desconocido y no puede saltarse la moderación. Es el mismo patrón que el precioEuros de las líneas de pedido: los campos que fija el servidor no se aceptan en la entrada, se rechazan.

Solución 2

Fallos detectados, tres en total:

1. lineas.0.precioEuros — campo desconocido en la línea: esquemaLinea es .strict() y solo admite cafeId y cantidad.
2. totalEuros — campo desconocido en la raíz: esquemaCrearPedido es .strict() y solo admite clienteId y lineas.
3. lineas.1.cafeId — caf_001 aparece repetido, lo detecta el superRefine.

Respuesta de la API:

Explicación para el integrador: los precios y el total los calcula el servidor a partir del catálogo en el momento de crear el pedido, y por eso la API no los acepta de entrada. Si los aceptara, cualquiera podría enviar precioEuros: 0.01 y comprar café de especialidad a un céntimo; el totalEuros enviado por el cliente, además, podría no cuadrar con la suma de las líneas, y entonces habría que decidir cuál de los dos números es el bueno. Rechazarlos elimina de golpe un fraude y una ambigüedad. La respuesta del 201 sí devuelve precioEuros por línea y totalEuros, ya calculados y congelados, que es lo que el cliente necesita mostrar.

Sobre el café repetido: el contrato prefiere una única línea por café con la cantidad agrupada, porque dos líneas del mismo producto hacen ambiguo el descuento de stock y complican la devolución parcial.

Solución 3

Zod permite un mapa de errores global que se aplica a todos los esquemas, sin tocar campo por campo:

Se instala una vez, en src/app.js, antes de montar las rutas:

Ahora el fallo del ejemplo anterior devuelve "Se esperaba number y se recibió string" en lugar del mensaje en inglés, sin haber tocado ni un campo del esquema.

Ventaja de tener codigo además de mensaje: el mensaje es para humanos —puede cambiar, traducirse o reescribirse para que se entienda mejor, y eso no rompe a nadie—. El codigo es para máquinas: un cliente puede escribir if (detalle.codigo === 'requerido') y confiar en que eso no cambiará, porque forma parte del contrato y está sujeto a las reglas de versionado de 02-07. Separar ambos permite mejorar la redacción de los mensajes cualquier martes sin publicar una versión nueva de la API. Es el mismo principio por el que los enumerados van en snake_case y no traducidos (02-05).

La API ya no acepta basura. Los esquemas de src/esquemas/ son ahora la definición ejecutable de qué entra: tipos, rangos, formatos de identificador, enumerados, fechas ISO-8601, precios con dos decimales y listas con longitud máxima; con .strict() para cumplir la entrada estricta de 02-05, z.coerce para convertir los parámetros de consulta que siempre llegan como texto, default() para que el controlador reciba los valores del contrato ya aplicados, y partial() para que PATCH exija lo justo. Un único middleware, validar(esquema, origen), aplica todo eso a body, query y params, sustituye la entrada por el valor ya parseado y traduce el ZodError al formato del contrato: 400 datos_invalidos para el cuerpo, 400 parametro_invalido para los parámetros, y todos los fallos a la vez en detalles, cada uno con su campo, su codigo estable y su mensaje.

Igual de importante es lo que no hemos metido en los esquemas. La existencia de un café, el stock disponible, un pedido ya pagado o el permiso para ver un recurso dependen del estado del sistema, cambian entre dos peticiones y tienen códigos de error de otra familia (409, no 400). Esa validación vive en el servicio, y algunas de sus comprobaciones tendrán que ocurrir dentro de la misma transacción que la escritura.

Justamente ahí vamos ahora. Todo lo construido hasta hoy se apoya en dos arrays en memoria que se vacían con cada reinicio de node --watch, que no admiten consultas serias y que no pueden garantizar que descontar stock de tres líneas sea una operación atómica. En 03-05, Persistencia y capa de acceso a datos, sustituiremos ese almacén por SQLite con better-sqlite3 detrás del patrón repositorio: esquema SQL con precio_centimos entero, migraciones versionadas y datos de siembra, sentencias preparadas que cierran la puerta a la inyección, consultas dinámicas seguras para los filtros de 02-06, transacciones para crear un pedido descontando stock, control de concurrencia optimista con conflicto_version y paginación por cursor de verdad. Y lo haremos sin tocar una sola línea de los controladores ni de los servicios, que es la promesa que hicimos en 03-01 al separar las capas.