Carmen Labs

Directory Layout

The recommended on-disk convention for storing and discovering MViews.

Directory Layout

The schema doesn't require a specific location for mview.json — source.path is enough to associate an MView with a file from anywhere. But implementations that share a discovery convention interoperate better: a tool can list "MViews for this file" without guessing where another tool put them.

Convention: colocated

Store the MView next to the file it represents, under a .mviews/ folder:

sales.csv
.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/
        ├── theme.css
        └── icon.svg

Convention: centralized

Or keep all MViews for a workspace under one root, with each manifest's source.path pointing back at its file:

.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/
"source": {
  "path": "../../sales.csv"
}

Which to use

Both are valid under the spec. A centralized workspace-level .mviews/ directory is useful when a tool wants one discovery root for the whole project. A colocated .mviews/ directory is useful when MViews should travel with the file itself (e.g., copying a single CSV plus its dashboard to another project).

Discovery

A conformant runtime discovering MViews for a given file should:

  1. Look for a matching centralized folder (e.g. <workspace>/.mviews/*/mview.json) and check each manifest's source.path against the file.
  2. Look for a colocated .mviews/ folder next to the file.
  3. Treat multiple MViews per file as normal — a CSV can have both a "Sales Dashboard" and a "Top Clients" view at once.

Resolving resources.path

resources.path (default ./resources) is always relative to the MView's own directory, never to the workspace root or the source file's directory.

Estructura de directorios

La convención recomendada en disco para guardar y descubrir MViews.

Estructura de directorios

El esquema no exige una ubicación específica para mview.json: source.path basta para asociar una MView con un archivo desde cualquier lugar. Pero las implementaciones que comparten una convención de descubrimiento interoperan mejor: una herramienta puede listar “MViews para este archivo” sin adivinar dónde las puso otra herramienta.

Convención: colocada junto al archivo

Guarda la MView junto al archivo que representa, bajo una carpeta .mviews/:

sales.csv
.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/
        ├── theme.css
        └── icon.svg

Convención: centralizada

O mantén todas las MViews de un workspace bajo una raíz, con el source.path de cada manifiesto apuntando de vuelta a su archivo:

.mviews/
└── sales-dashboard/
    ├── mview.json
    ├── parser.ts
    ├── Dashboard.tsx
    └── resources/
"source": {
  "path": "../../sales.csv"
}

Cuál usar

Ambas son válidas según la especificación. Un directorio .mviews/ centralizado a nivel de workspace es útil cuando una herramienta quiere una sola raíz de descubrimiento para todo el proyecto. Un directorio .mviews/ colocado junto al archivo es útil cuando las MViews deben viajar con el propio archivo (por ejemplo, al copiar un CSV individual junto con su dashboard a otro proyecto).

Descubrimiento

Un runtime conforme que descubre MViews para un archivo dado debería:

  1. Buscar una carpeta centralizada coincidente (por ejemplo, <workspace>/.mviews/*/mview.json) y revisar el source.path de cada manifiesto contra el archivo.
  2. Buscar una carpeta .mviews/ colocada junto al archivo.
  3. Tratar múltiples MViews por archivo como algo normal: un CSV puede tener una vista “Sales Dashboard” y una vista “Top Clients” al mismo tiempo.

Resolución de resources.path

resources.path (por defecto ./resources) siempre es relativo al propio directorio de la MView, nunca a la raíz del workspace ni al directorio del archivo fuente.