Schema Reference

Every field in mview.json, with valid and invalid examples.

Schema Reference

Every mview.json manifest must validate against:

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

Field table

Field	Type	Required	Description
`$schema`	`string` (const)	yes	Must be exactly `https://schemas.carmenlabs.com/mview/v1/schema.json`.
`id`	`string`	yes	Unique identifier. Pattern: `^[a-z0-9][a-z0-9._-]*$`.
`name`	`string`	yes	Human-readable display name.
`description`	`string`	no	Human-readable summary of what the view shows.
`version`	`string`	yes	Semantic version of the MView itself: `MAJOR.MINOR.PATCH`.
`prompt`	`string`	yes	Prompt used to generate this mutation.
`runtime`	`object`	yes	Rendering runtime required by the MView.
`runtime.environment`	`string`	yes	Execution environment. V1 allows `"web"`, `"desktop"`, `"terminal"`, or `"other"`.
`runtime.renderer`	`string`	yes	Required renderer/adapter. This is an open implementation-defined identifier, for example `"react"`, `"solid"`, `"html"`, or `"pdf"`.
`runtime.version`	`string`	no	Compatible semver range for the renderer, for example `"^19.0.0"`.
`author`	`string`	no	Author name or identifier.
`license`	`string`	no	SPDX license identifier.
`icon`	`string`	no	Relative path to an icon asset.
`accepts`	`string[]`	no	Capabilities this MView needs from the runtime. See Capabilities.
`source`	`object`	no	The source file this MView is derived from.
`source.path`	`string`	yes, if `source` present	Relative path to the source file.
`source.contentHash`	`string`	no	Hash of the source file at creation/last validation time.
`entry`	`object`	yes	Executable entry points.
`entry.parser`	`string`	yes	Relative path to the parser module.
`entry.component`	`string`	yes	Relative path to the view component.
`resources`	`object`	no	Location of static assets.
`resources.path`	`string`	no	Relative path to the resources directory. Default `./resources`.
`settings`	`object`	no	Default settings exposed to parser and component.
`metadata`	`object`	no	Free-form implementation metadata. Must not drive runtime behavior.

additionalProperties: false applies at every level — manifests with unknown fields are invalid.

`id`

Lowercase letters, digits, dots, underscores, and hyphens only.

Valid: sales-dashboard, invoice.tax-view, logs_timeline Invalid: Sales Dashboard, dashboard final, ventas/2026

`prompt`

The manifest must preserve the original prompt used to generate the mutation. This lets the user see how the view was created and provides an editable starting point if the source file changes and the mutation is no longer compatible.

"prompt": "Create an executive view for monthly sales, top clients, and totals."

The prompt is re-executable provenance, not runtime configuration: it must not replace settings for values that directly affect rendering.

`runtime`

V1 defines multiple execution environments ("web", "desktop", "terminal", "other") with an explicit renderer. runtime.renderer is not a closed list of renderers supported by the specification: it is the identifier for the rendering path the manifest requires. React and Solid are common examples for web, but an implementation can publish other values such as "html", "pdf", or a custom renderer for different environments.

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

For Solid, the manifest declares another renderer identifier:

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

runtime.version is optional and is interpreted as a compatible semver range for the renderer, not as an exact version. The specification does not require any runtime to implement a specific renderer; each implementation must document which runtime.renderer values it accepts and how to execute or produce that kind of view. Implementations must reject manifests whose environment, renderer, or version range they don't support, rather than guessing.

`accepts`

Declares what kind of normalized input the parser expects — a capability, not a file extension. Full list and normalizer shapes: Capabilities.

`source`

Optional pointer to the file this MView was derived from.

"source": {
  "path": "../sales.csv",
  "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
}

path is always relative. contentHash lets a runtime detect drift between the file and the last time the MView was created or validated, and prompt for regeneration.

`entry`

"entry": {
  "parser": "./parser.ts",
  "component": "./Dashboard.tsx"
}

Both paths are relative to the MView's own directory, never absolute. The parser and component contracts are specified separately: Parser Contract, Component Contract.

`settings`

Initial, editable configuration surfaced to the parser and/or component.

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

Unlike metadata, settings is allowed to affect rendering.

`metadata`

Free-form provenance information — who/what generated the MView, when, with which model.

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

metadata must never gate or change runtime behavior. If a value needs to affect rendering, it belongs in settings.

Full example

{
  "$schema": "https://schemas.carmenlabs.com/mview/v1/schema.json",
  "id": "sales-dashboard",
  "name": "Sales Dashboard",
  "description": "Executive dashboard generated from sales.csv.",
  "version": "1.0.0",
  "prompt": "Create an executive dashboard from sales.csv showing monthly sales, top clients, and total sales.",
  "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-11T05:00:00Z"
  }
}

Raw schema

The canonical machine-readable schema is served at schemas.carmenlabs.com/mview/v1/schema.json. Validate manifests against that URL directly — do not hardcode a copy where it can drift.

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

Campo	Tipo	Requerido	Descripción
`$schema`	`string` (const)	sí	Debe ser exactamente `https://schemas.carmenlabs.com/mview/v1/schema.json`.
`id`	`string`	sí	Identificador único. Patrón: `^[a-z0-9][a-z0-9._-]*$`.
`name`	`string`	sí	Nombre visible para humanos.
`description`	`string`	no	Resumen legible de lo que muestra la vista.
`version`	`string`	sí	Versión semántica de la MView: `MAJOR.MINOR.PATCH`.
`prompt`	`string`	sí	Prompt usado para generar esta mutación.
`runtime`	`object`	sí	Runtime de renderizado requerido por la MView.
`runtime.environment`	`string`	sí	Entorno de ejecución. V1 permite `"web"`, `"desktop"`, `"terminal"` u `"other"`.
`runtime.renderer`	`string`	sí	Renderer/adaptador requerido. Es un identificador abierto definido por la implementación, por ejemplo `"react"`, `"solid"`, `"html"` o `"pdf"`.
`runtime.version`	`string`	no	Rango semver compatible del renderer, por ejemplo `"^19.0.0"`.
`author`	`string`	no	Nombre o identificador del autor.
`license`	`string`	no	Identificador de licencia SPDX.
`icon`	`string`	no	Ruta relativa a un asset de icono.
`accepts`	`string[]`	no	Capacidades que esta MView necesita del runtime. Ver Capacidades.
`source`	`object`	no	El archivo fuente del que deriva esta MView.
`source.path`	`string`	sí, si `source` está presente	Ruta relativa al archivo fuente.
`source.contentHash`	`string`	no	Hash del archivo fuente al momento de creación o última validación.
`entry`	`object`	sí	Puntos de entrada ejecutables.
`entry.parser`	`string`	sí	Ruta relativa al módulo parser.
`entry.component`	`string`	sí	Ruta relativa al componente de vista.
`resources`	`object`	no	Ubicación de assets estáticos.
`resources.path`	`string`	no	Ruta relativa al directorio de recursos. Por defecto `./resources`.
`settings`	`object`	no	Configuración por defecto expuesta al parser y al componente.
`metadata`	`object`	no	Metadatos libres de implementación. No deben dirigir el comportamiento del runtime.

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 el archivo 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. React y Solid son ejemplos frecuentes para web, pero una implementación puede publicar otros valores como "html", "pdf" o un renderer propio para diferentes entornos.

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

Para Solid, el manifiesto declara otro identificador de renderer:

"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.

`source`

Puntero opcional al archivo del que derivó esta MView.

"source": {
  "path": "../sales.csv",
  "contentHash": "sha256:8d969eef6ecad3c29a3a629280e686cff8ca58e3f3f2d4d0c7d7f9f2e2f0f4ab"
}

path siempre es relativo. 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.

`entry`

"entry": {
  "parser": "./parser.ts",
  "component": "./Dashboard.tsx"
}

Ambas rutas son relativas al propio directorio de la MView, nunca absolutas. 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

{
  "$schema": "https://schemas.carmenlabs.com/mview/v1/schema.json",
  "id": "sales-dashboard",
  "name": "Sales Dashboard",
  "description": "Executive dashboard generated from sales.csv.",
  "version": "1.0.0",
  "prompt": "Create an executive dashboard from sales.csv showing monthly sales, top clients, and total sales.",
  "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-11T05:00: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.