Validador de datos

Descripción

Este módulo comprueba los datos de entrada contra un esquema que tú defines y devuelve un informe de validación. Opcionalmente limpia los campos (recortar espacios, quitar HTML, pasar a minúsculas…) antes de validarlos, de modo que el nodo siguiente recibe los datos ya normalizados.

Acepta un objeto o una lista de objetos. En listas valida cada elemento y reporta rutas como data[0].campo.

Por defecto el módulo no detiene el flujo si hay errores: devuelve los datos junto con validation, y un nodo de decisión posterior puede bifurcar según validation.success. Si prefieres que la ejecución se pare con un error, activa Detener el flujo si falla.

Configuración

Parámetro	Tipo	Requerido	Descripción
schema	json	Sí	Esquema con las reglas de cada campo (ver abajo). Puede escribirse como objeto o como texto JSON
path	text	No	Ruta al objeto o lista que se valida, por ejemplo data (el contenido de un formulario). Vacío = todos los datos del nodo anterior
resultKey	text	No	Campo de data donde se añade el resultado (por defecto validation). Con una lista como entrada solo se añade si lo indicas, y la lista pasa a ser items
stopOnError	boolean	No	Si está activo y algo no es válido, la ejecución se detiene con un error que resume los fallos
errorMessage	text	No	Texto que encabeza el error cuando se detiene el flujo

Reglas de cada campo

Regla	Qué comprueba
required	El campo existe y no es null
notEmpty	Un texto que no sea solo espacios, o una lista con elementos
type	string, number, boolean, object, array o null
enum	El valor está en la lista permitida
minLength / maxLength	Longitud mínima / máxima de un texto
min / max	Valor mínimo / máximo de un número
format	email, phone, url, date (AAAA-MM-DD, fecha real), datetime, integer, uuid
pattern	Expresión regular que debe cumplir el texto (patternFlags opcional, por ejemplo i)
message	Mensaje propio que sustituye al mensaje de esa regla
items	Sub-esquema para cada elemento de una lista (type: "array")
clean	Lista de limpiezas que se aplican antes de validar (ver abajo)

Los textos vacíos en campos opcionales no se comprueban contra longitud, formato ni patrón: para exigirlos usa required o notEmpty.

Limpiezas (clean)

Se aplican en el orden indicado y solo a textos:

Limpieza	Efecto
trim	Quita espacios al principio y al final
collapse	Convierte varios espacios o saltos de línea seguidos en uno y recorta
stripHtml	Quita las etiquetas HTML
lower / upper	Minúsculas / mayúsculas
cut:N	Corta a N caracteres

Salida

{
  "nextModule": "siguiente-nodo",
  "data": {
    "email": "mal",
    "validation": {
      "success": false,
      "errors": [
        { "field": "data.email", "message": "Invalid email format" },
        { "field": "data.telefono", "message": "Field is required" }
      ],
      "totalValidated": 1
    }
  }
}

El resultado va dentro de data (data.validation), porque es lo que recibe el nodo siguiente: un nodo de decisión puede usar la condición data.validation.success === true. data son los datos de entrada (limpios si el esquema usa clean; el objeto original nunca se modifica). Los mensajes de error están en inglés e incluyen la ruta completa del campo; usa message para ponerlos en tu idioma.

Con Detener el flujo si falla y algún error, el nodo termina con un error del tipo Solicitud no válida — data.email: Invalid email format; data.telefono: Field is required (muestra los primeros 5 fallos).

Ejemplos de Uso

Formulario de contacto: limpiar y exigir lo importante

{
  "label": "Validar solicitud",
  "stopOnError": true,
  "errorMessage": "Solicitud no válida",
  "schema": {
    "nombre":   { "required": true, "notEmpty": true, "clean": ["stripHtml", "collapse", "cut:120"] },
    "email":    { "required": true, "format": "email", "clean": ["trim", "lower"], "message": "Escribe un email válido" },
    "telefono": { "format": "phone", "clean": ["collapse", "cut:40"] },
    "motivo":   { "maxLength": 500, "clean": ["stripHtml", "collapse", "cut:500"] }
  }
}

Después de un Webhook o un Trigger Form, los campos recibidos ya están en el primer nivel de los datos: deja la ruta vacía. Solo hace falta indicarla (por ejemplo data) si quien llama envía los campos dentro de otro objeto, como { "data": { "email": "…" } }.

Lista de pedidos con campos obligatorios

{
  "label": "Comprobar pedidos",
  "schema": {
    "referencia": { "required": true, "pattern": "^[A-Z]{2}-\\d{3,}$" },
    "total": { "required": true, "type": "number", "min": 0 },
    "estado": { "enum": ["nuevo", "pagado", "enviado"] },
    "lineas": { "type": "array", "notEmpty": true, "items": { "sku": { "required": true }, "cantidad": { "type": "number", "min": 1 } } }
  }
}

Notas

• El módulo no modifica nunca el objeto de entrada: con clean devuelve una copia limpia.
• La validación es recursiva para los campos de tipo array con items, y clean también se aplica dentro de items.
• validation.success es true solo si no hay ningún error; totalValidated indica cuántos objetos se validaron.
• Un patrón (pattern) inválido o un formato desconocido no rompe el flujo: aparece como error de validación de ese campo.
• Se recomienda un nodo de decisión después de este módulo para bifurcar según validation.success, salvo que uses Detener el flujo si falla.

Nodos Relacionados

• decision (Nodo de decisión - para actuar según resultado de validación)
• multiroute (Multiroute - para bifurcar flujo)
• editFields (Edit Fields - para dar forma a los datos ya validados)