Referencia del esquema

Cada campo de mview.json, con ejemplos válidos e inválidos.

Referencia del esquema

Todo manifiesto mview.json debe validar contra:

https://schemas.carmenlabs.com/mview/v1/schema.json

Tabla de campos

additionalProperties: false aplica en todos los niveles: los manifiestos con campos desconocidos son inválidos.

id

Solo letras minúsculas, dígitos, puntos, guiones bajos y guiones.

Válido: sales-dashboard, invoice.tax-view, logs_timeline Inválido: Sales Dashboard, dashboard final, ventas/2026

prompt

El manifiesto debe conservar el prompt original usado para generar la mutación. Esto permite mostrarle al usuario cómo se creó la vista y ofrece un punto de partida editable si la fuente cambia y la mutación deja de ser compatible.

"prompt": "Crea una vista ejecutiva para revisar ventas mensuales, clientes principales y totales."

El prompt es procedencia reejecutable, no configuración de runtime: no debe reemplazar a settings para valores que afecten directamente el renderizado.

runtime

V1 define múltiples entornos de ejecución ("web", "desktop", "terminal", "other") con renderer explícito. runtime.renderer no es una lista cerrada de renderers soportados por la especificación: es el identificador del camino de renderizado que el manifiesto requiere.

Renderers recomendados para web

Para environment: "web", recomendamos este orden de prioridad:

1. "html" — HTML puro (+ CSS/JS inline o tags <style>/<script>). Opción más simple, cero dependencias, funciona en cualquier navegador.
2. "html+js" — HTML con archivos JavaScript separados para interactividad.
3. "react" — Para UIs complejas que justifiquen un framework.
4. "solid" — Alternativa a React con reactividad granular.

Ejemplo con HTML (recomendado para vistas simples):

"runtime": {
  "environment": "web",
  "renderer": "html"
}

Esta es la opción más liviana. El parser puede ser un simple archivo .js, y el componente es un archivo .html plano. Sin build step, sin transpilación, sin overhead de framework.

Ejemplo con React (para vistas interactivas complejas):

"runtime": {
  "environment": "web",
  "renderer": "react",
  "version": "^19.0.0"
}

Ejemplo con Solid:

"runtime": {
  "environment": "web",
  "renderer": "solid",
  "version": "^1.9.0"
}

runtime.version es opcional y se interpreta como un rango semver compatible del renderer, no como una versión exacta. La especificación no obliga a ningún runtime a implementar un renderer concreto; cada implementación debe documentar qué valores de runtime.renderer acepta y cómo ejecutar o producir ese tipo de vista. Las implementaciones deben rechazar manifiestos cuyo environment, renderer o rango de versión no soportan, en lugar de inferir.

accepts

Declara qué tipo de entrada normalizada espera el parser: una capacidad, no una extensión de archivo. Lista completa y formas normalizadas: Capacidades.

accepts describe la salida normalizada esperada; no selecciona por sí solo el código que lee la fuente. Para eso se usan source.adapters o source.files[].adapters.

source

Puntero opcional al archivo o a la selección de archivos de la que derivó esta MView.

Fuente de archivo

source.kind es opcional y su valor por defecto es "file". Por lo tanto, ambos manifiestos siguientes tienen el mismo significado:

"source": {
  "path": "../sales.csv",
  "adapters": ["csv-table"],
  "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
}

"source": {
  "kind": "file",
  "path": "../sales.csv",
  "adapters": ["csv-table"],
  "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
}

path siempre es relativo al directorio de la MView. contentHash permite que un runtime detecte drift entre el archivo y la última vez que la MView fue creada o validada, y pida regeneración. files NO DEBE aparecer en una fuente de archivo.

Fuente de directorio

Una fuente de directorio debe declarar kind: "directory" y enumerar explícitamente los archivos que forman la entrada:

"accepts": ["filesystem"],
"source": {
  "kind": "directory",
  "path": "../reportes",
  "files": [
    {
      "path": "enero.csv",
      "accepts": ["table"],
      "adapters": ["csv-table"],
      "contentHash": "sha256:111..."
    },
    {
      "path": "notas/resumen.md",
      "accepts": ["markdown", "document"],
      "adapters": ["markdown-document"],
      "contentHash": "sha256:222..."
    }
  ],
  "contentHash": "sha256:333..."
}

files debe contener al menos un elemento. Sus rutas son relativas a source.path, usan / como separador y deben ser únicas. No pueden ser absolutas, estar vacías, contener segmentos . o .., ni resolver fuera del directorio mediante enlaces simbólicos. El runtime lee únicamente los archivos enumerados: no hay recorrido recursivo ni inclusión implícita de archivos nuevos.

Cada files[].accepts debe contener al menos una capacidad, sin duplicados, y declara en orden de preferencia las capacidades con las que el runtime intentará normalizar ese archivo. El accepts de la MView debe incluir "filesystem", porque el parser recibe la colección normalizada completa y no cada archivo como una ejecución independiente.

Hash canónico de un directorio

Cada files[].contentHash, cuando está presente, es sha256: seguido del SHA-256 de los bytes originales del archivo, antes de normalizarlo. source.contentHash, cuando está presente en una fuente de directorio, se calcula así:

1. Para cada archivo, construir un objeto con path normalizado y su contentHash real.
2. Ordenar los objetos lexicográficamente por los bytes UTF-8 de path. La comparación es sensible a mayúsculas y minúsculas.
3. Serializar el array mediante JSON Canonicalization Scheme (RFC 8785).
4. Calcular SHA-256 sobre los bytes UTF-8 de esa serialización y anteponer sha256:.

La representación lógica anterior al hash es:

[
  { "path": "enero.csv", "contentHash": "sha256:111..." },
  { "path": "notas/resumen.md", "contentHash": "sha256:222..." }
]

El hash agregado cambia si cambia el contenido, la ruta o la membresía de la selección, pero no si solo se reordena source.files en el manifiesto.

entry

"entry": {
  "parser": "./parser.js",
  "component": "./view.html"
}

Ambas rutas son relativas al propio directorio de la MView, nunca absolutas. Para vistas basadas en HTML, el parser es típicamente un archivo .js simple y el componente es un archivo .html cuyo script lee las props desde el global window.mview que inyecta el runtime. Para vistas basadas en frameworks (React, Solid), usarías archivos .tsx o .jsx que reciben las props como argumento.

Los contratos del parser y componente se especifican por separado: Contrato del parser, Contrato del componente.

settings

Configuración inicial editable expuesta al parser y/o componente.

"settings": {
  "currency": "USD",
  "showTopClients": true,
  "maxRows": 10
}

A diferencia de metadata, settings puede afectar el renderizado.

metadata

Información libre de procedencia: quién o qué generó la MView, cuándo y con qué modelo.

"metadata": {
  "createdBy": "llm",
  "model": "gpt-5.5",
  "createdAt": "2026-07-11T05:00:00Z"
}

metadata nunca debe condicionar ni cambiar el comportamiento del runtime. Si un valor necesita afectar el renderizado, pertenece en settings.

Ejemplo completo (HTML)

{
  "$schema": "https://schemas.carmenlabs.com/mview/v1/schema.json",
  "id": "sales-summary",
  "name": "Resumen de Ventas",
  "description": "Resumen simple de ventas desde sales.csv.",
  "version": "1.0.0",
  "prompt": "Muestra el total de ventas y los 3 clientes principales en una vista simple.",
  "runtime": {
    "environment": "web",
    "renderer": "html"
  },
  "author": "Victor Avila",
  "license": "MIT",
  "accepts": ["table"],
  "source": {
    "path": "../sales.csv",
    "adapters": ["csv-table"],
    "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
  },
  "entry": {
    "parser": "./parser.js",
    "component": "./view.html"
  },
  "settings": {
    "currency": "USD",
    "topClientsLimit": 3
  },
  "metadata": {
    "createdBy": "llm",
    "model": "gpt-5.5",
    "createdAt": "2026-07-16T21:26:00Z"
  }
}

Ejemplo completo (React)

Para dashboards interactivos más complejos:

{
  "$schema": "https://schemas.carmenlabs.com/mview/v1/schema.json",
  "id": "sales-dashboard",
  "name": "Dashboard de Ventas",
  "description": "Dashboard interactivo con gráficos y filtros.",
  "version": "1.0.0",
  "prompt": "Crea un dashboard interactivo desde sales.csv con gráficos, filtros y drill-down.",
  "runtime": {
    "environment": "web",
    "renderer": "react",
    "version": "^19.0.0"
  },
  "author": "Victor Avila",
  "license": "MIT",
  "icon": "./resources/icon.svg",
  "accepts": ["table"],
  "source": {
    "path": "../sales.csv",
    "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
  },
  "entry": {
    "parser": "./parser.ts",
    "component": "./Dashboard.tsx"
  },
  "resources": {
    "path": "./resources"
  },
  "settings": {
    "currency": "USD",
    "topClientsLimit": 10
  },
  "metadata": {
    "createdBy": "llm",
    "model": "gpt-5.5",
    "createdAt": "2026-07-16T21:26:00Z"
  }
}

Esquema raw

El esquema canónico legible por máquina se sirve en schemas.carmenlabs.com/mview/v1/schema.json. Valida manifiestos directamente contra esa URL: no hardcodees una copia que pueda desactualizarse.