¿Cuál es la Diferencia Entre Manifest, Report y Finding? ¿Qué Significan los Términos de Jerarquía de Datos en Arquitectura de Software? ¿Por Qué Diseñar una API en Capas? ¡Cómo Difieren Metadata, Artifact y Payload!

¿Te has encontrado a menudo con términos como Manifest, Report, Finding y Evidence al leer documentación de API, resultados de escáneres de seguridad o registros de CI/CD? No son sintaxis de un lenguaje de programación específico, sino términos de jerarquía de datos estándar en la industria. ¿Qué significan realmente estos términos?

Concepto Core: Entendiendo la Jerarquía de Datos Mediante un “Chequeo Médico”

Podemos imaginarlos como el proceso de hacerse un chequeo médico en un hospital. Estos cuatro términos corresponden exactamente a niveles de datos, desde resúmenes de alto nivel hasta datos brutos en el nivel más bajo.

Término	Analogía del Chequeo Médico	Explicación en Arquitectura de Software
`Manifest`	Formulario de Registro	Declara qué elementos se ejecutarán, versiones y configuraciones; son datos descriptivos.
`Report`	Informe de Chequeo Completo	Resumen completo tras la ejecución, incluyendo estado general y resultados de auditoría.
`Finding`	Anotación en Rojo en el Informe	Hallazgo específico remarcado en el informe, como “Hipertensión detectada” o fallo de seguridad.
`Evidence`	Tira de Datos del Tensiómetro	Evidencia objetiva y bruta que respalda los hallazgos, como registros de log o mediciones.

Estos términos no son palabras reservadas de un lenguaje de programación, sino modelos de datos compartidos de la industria.

Podemos utilizar un diagrama Mermaid para ilustrar las relaciones de inclusión y flujo de datos entre estos cuatro conceptos:

  graph TD
    A["Manifest (Espec. de Ejecución/Metadatos)"] -->|Define Alcance y Ejecución| B["Report (Informe Resumen Completo)"]
    B -->|Contiene Múltiples| C["Finding (Hallazgo Específico/Observación)"]
    C -->|Asocia Múltiples| D["Evidence (Evidencia Bruta Objetiva)"]

¿Por Qué Diseñar por Capas? Las 3 Grandes Ventajas de la Jerarquía de Datos

¿Por qué dividir los datos con tanto detalle en lugar de meter todo en un enorme objeto JSON? Este diseño ofrece varias ventajas clave:

Un excelente diseño de arquitectura de API permite que la interfaz cargue más fluido y hace que los datos sean más confiables y extensibles.

Ventaja	Explicación
Separación de Responsabilidades	El frontend puede cargar primero el resumen de `Finding` para vista rápida, solicitando el pesado `Evidence` solo cuando sea necesario profundizar.
Alta Credibilidad	Proporcionar `Evidence` demuestra que un `Finding` no es un falso positivo, aumentando notablemente la auditabilidad del sistema.
Extensibilidad Flexible	Un solo `Finding` puede asociarse libremente con múltiples `Evidence` sin romper el formato de datos original.

Otros Términos Comunes Complementarios: Metadata, Artifact y Payload

Además de los cuatro niveles principales, al diseñar API, construir pipelines o definir formatos de transmisión, verás con frecuencia estos tres términos: Metadata, Artifact y Payload:

Término	Definición Core	Analogía de la Vida Real	Ejemplo de Aplicación Práctica en Software
`Metadata`	Datos que describen los propios datos	Etiqueta de envío en un paquete, datos EXIF de una foto	`HTTP Header`, marca de tiempo `timestamp`, información de paginación `page`.
`Artifact`	Producto físico generado tras un proceso	Coche fabricado en una planta, CD de chequeo médico	Archivo `.apk` compilado, `Docker Image`, informe `PDF` de auditoría.
`Payload`	Datos de negocio principales a transmitir	El smartphone real dentro de la caja del paquete	Contenido principal de negocio `JSON` en el `HTTP POST Body`.

Payload es como el objeto dentro de un paquete postal, mientras que Metadata es la etiqueta de envío pegada por fuera.

Para comprender mejor cómo trabajan juntos estos tres conceptos, observemos una estructura de datos típica de API Request:

{
  "metadata": {
    "version": "v1.2.0",
    "timestamp": "2026-08-02T15:08:41Z",
    "request_id": "req-98765"
  },
  "payload": {
    "report_id": "REP-2026-001",
    "status": "COMPLETED",
    "artifact_url": "https://example.com/artifacts/build-report.pdf"
  }
}

En este ejemplo de JSON:

metadata proporciona el contexto de transmisión y entorno (versión, marca de tiempo, ID de solicitud).
payload contiene los datos reales de lógica de negocio (ID de informe, estado).
artifact_url apunta al archivo físico real generado por esta tarea de compilación (Artifact).

El Poder del Vocabulario Compartido: Puente de Comunicación Entre Sistemas

Cuando diferentes herramientas y equipos adoptan este modelo de datos similar (Report -> Findings -> Evidence), los costes de comunicación entre equipos se reducen drásticamente.

Imagina que el Report generado por tu herramienta de CI/CD pueda transmitirse directamente y sin fricción al sistema de seguridad para su análisis: ese es el poder de integración del lenguaje de dominio compartido.

  sequenceDiagram
    autonumber
    actor CI as CI/CD Pipeline
    participant Scanner as Escáner de Seguridad
    participant Dashboard as Panel de Control
    
    CI->>Scanner: Proporciona Manifest para Escanear
    Scanner->>Scanner: Genera Report y Findings
    Scanner->>Dashboard: Envía Payload Estructurado (Finding + Evidence)
    Dashboard-->>CI: Muestra Resultados de Auditoría

Resumen

En realidad, el objetivo de estos términos es resolver problemas de comunicación y estructuración de datos entre sistemas a gran escala.

Al integrar sistemas o diseñar API, intenta incorporar estos conceptos de jerarquía de datos en la estructura de tu Payload, ¡haciendo que tu diseño de sistema sea más profesional y altamente extensible!