Carmen LabsCarmen Labs
MView V1

Capabilities

The accepts enum and the normalized shape the runtime guarantees for each capability.

Capabilities

accepts declares what kind of normalized data the parser expects — not a file extension. A .csv, a .xlsx, and a database export could all normalize to table.

Source Adapters

An MView always starts from the original source file. A Source Adapter is the component that interprets its bytes and produces the normalized input consumed by the parser. It may be written in any language, as long as the runtime can invoke it through the protocol that runtime documents.

source.adapters declares adapter identifiers in preference order. For a directory source, each source.files item may declare its own adapters. The runtime must select a compatible adapter before executing the parser and must retain the original-byte contentHash in the execution context.

The adapter must not produce a MView's visual data model directly: it produces a normalized shape defined by a capability such as table, markdown, or structured. The parser turns that general shape into the view-specific model consumed by the component.

Normalized output may be cached temporarily, but it is never the source of truth and must be invalidated when the bytes, configuration, or adapter version changes. When the view opens or is regenerated, the runtime reads the original source again and repeats adaptation.

Full enum (V1)

text  document  markdown  html  table  tree  graph  timeseries
image  binary  structured  key-value  filesystem  code  log
dataset  geo  audio  video  custom

Minimum viable normalizers

An implementation does not need to support every capability to be spec-conformant — but for the capabilities it does support, the normalized shape below is required so parsers are portable across runtimes.

table

For CSV, spreadsheets, and other tabular sources.

{
  columns: string[],
  rows: Record<string, string>[]
}

text

For plain text, logs, source code, or Markdown treated as raw text.

{
  text: string
}

markdown

{
  raw: string,
  headings: Array<{ level: number; text: string }>
}

tree / structured

For JSON, XML, YAML.

{
  value: unknown
}

filesystem

For a source with source.kind: "directory". It does not provide filesystem access: it represents only the files enumerated in source.files, already read and normalized by the runtime.

{
  path: string,
  files: Array<{
    path: string,
    capability: string,
    input: unknown,
    contentHash: string
  }>
}
  • path identifies the declared source directory.
  • files is sorted lexicographically by the UTF-8 bytes of path, using the same rule as the canonical directory hash. The order of source.files in the manifest does not affect the input.
  • Each file's path is relative to the source directory.
  • capability is the first supported capability from source.files[].accepts that the adapter used to normalize the file.
  • input has the normalized shape defined by that capability.
  • contentHash is the SHA-256 hash calculated by the runtime over the original bytes, even if it was not persisted in the manifest.

The runtime MUST fail before executing the parser if it cannot read a selected file or does not support any of its declared capabilities. It must not silently omit files.

Choosing capabilities

Source typeaccepts
CSV / XLSX / any tabular data["table"]
Markdown["markdown", "document"]
JSON / YAML / XML["tree", "structured"]
Logs["log", "text"]
Source code["code", "text"]
Explicit selection of files in a directory["filesystem"]

A capability is a claim about the information the parser will receive, not about whether the source can be read that way. Many sources can be decoded under a capability without carrying their information in it — bytes that read as text are not necessarily the source's text. Before declaring a capability, confirm against the real source that normalizing it under that capability yields the information the user asked to view. If no supported capability does, do not declare the one that merely loads without error: the information must first exist in a representation whose normalization carries it, or the MView cannot be created for that source.

Capabilities beyond the minimum set

graph, timeseries, image, geo, audio, video, dataset, key-value, binary, html, document, and custom are reserved in the enum for V1 so manifests can declare intent even where a given runtime doesn't yet ship a normalizer for them. A runtime that receives an accepts value it can't normalize should fail clearly at load time rather than silently passing through unnormalized data — see Security Model and Versioning for how new normalizers get added without breaking existing manifests.

Capacidades

El enum accepts y la forma normalizada que el runtime garantiza para cada capacidad.

Capacidades

accepts declara qué tipo de datos normalizados espera el parser, no una extensión de archivo. Un .csv, un .xlsx y una exportación de base de datos podrían normalizarse todos como table.

Source Adapters

Una MView siempre parte del archivo fuente original. Un Source Adapter es el componente que interpreta sus bytes y produce la entrada normalizada consumida por el parser. Su implementación puede estar escrita en cualquier lenguaje, siempre que el runtime pueda invocarla mediante el protocolo que documente.

source.adapters declara identificadores de adapters en orden de preferencia. Para una fuente de directorio, cada elemento de source.files puede declarar sus propios adapters. El runtime debe seleccionar un adapter compatible antes de ejecutar el parser y debe conservar el contentHash de los bytes originales en el contexto de ejecución.

El adapter no debe producir directamente el modelo visual de una MView: debe producir una forma normalizada definida por una capacidad como table, markdown o structured. El parser convierte esa forma general en el modelo específico que consume el componente.

La salida normalizada puede cachearse temporalmente, pero nunca es la fuente de verdad y debe invalidarse cuando cambien los bytes, la configuración o la versión del adapter. Al abrir o regenerar la vista, el runtime vuelve a leer la fuente original y repite la adaptación.

Enum completo (V1)

text  document  markdown  html  table  tree  graph  timeseries
image  binary  structured  key-value  filesystem  code  log
dataset  geo  audio  video  custom

Normalizadores mínimos viables

Una implementación no necesita soportar todas las capacidades para cumplir la especificación; pero para las capacidades que sí soporta, la forma normalizada siguiente es requerida para que los parsers sean portables entre runtimes.

table

Para CSV, planillas y otras fuentes tabulares.

{
  columns: string[],
  rows: Record<string, string>[]
}

text

Para texto plano, logs, código fuente o Markdown tratado como texto raw.

{
  text: string
}

markdown

{
  raw: string,
  headings: Array<{ level: number; text: string }>
}

tree / structured

Para JSON, XML, YAML.

{
  value: unknown
}

filesystem

Para una fuente con source.kind: "directory". No entrega acceso al filesystem: representa únicamente los archivos enumerados en source.files, ya leídos y normalizados por el runtime.

{
  path: string,
  files: Array<{
    path: string,
    capability: string,
    input: unknown,
    contentHash: string
  }>
}
  • path identifica el directorio fuente declarado.
  • files se ordena lexicográficamente por los bytes UTF-8 de path, con la misma regla usada para calcular el hash canónico del directorio. El orden de source.files en el manifiesto no afecta la entrada.
  • path de cada archivo es relativo al directorio fuente.
  • capability es la primera capacidad soportada de source.files[].accepts que el adapter usó para normalizarlo.
  • input tiene la forma normalizada definida por esa capacidad.
  • contentHash es el hash SHA-256 calculado por el runtime sobre los bytes originales, aunque no se haya persistido en el manifiesto.

El runtime DEBE fallar antes de ejecutar el parser si no puede leer un archivo seleccionado o no soporta ninguna de sus capacidades declaradas. No debe omitir archivos silenciosamente.

Elección de capacidades

Tipo de fuenteaccepts
CSV / XLSX / cualquier dato tabular["table"]
Markdown["markdown", "document"]
JSON / YAML / XML["tree", "structured"]
Logs["log", "text"]
Código fuente["code", "text"]
Selección explícita de archivos de una carpeta["filesystem"]

Una capacidad es una afirmación sobre la información que recibirá el parser, no sobre si la fuente puede leerse de esa manera. Muchas fuentes pueden decodificarse bajo una capacidad sin portar su información en ella: bytes que se leen como texto no son necesariamente el texto de la fuente. Antes de declarar una capacidad, confirma contra la fuente real que normalizarla bajo esa capacidad produce la información que el usuario pidió ver. Si ninguna capacidad soportada lo logra, no declares la que simplemente carga sin error: la información debe existir primero en una representación cuya normalización la porte, o la MView no puede crearse para esa fuente.

Capacidades fuera del conjunto mínimo

graph, timeseries, image, geo, audio, video, dataset, key-value, binary, html, document y custom están reservadas en el enum para V1, de modo que los manifiestos puedan declarar intención incluso cuando un runtime dado todavía no incluya un normalizador para ellas. Un runtime que recibe un valor de accepts que no puede normalizar debe fallar claramente al cargar, en lugar de pasar datos sin normalizar silenciosamente. Ver Modelo de seguridad y Versionado para cómo se agregan nuevos normalizadores sin romper manifiestos existentes.