Carmen LabsCarmen Labs
MView V1

Directory Layout

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

Directory Layout

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

Convention: colocated

Store the MView directly next to the file it represents. Each MView package is stored in a directory whose name ends in .mview:

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

Convention: centralized

Or keep all MViews for a workspace inside a centralized .mviews/ folder, with each manifest's source.path pointing back at its file:

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

Which to use

Both are valid under the spec. The colocated location is the simple option for keeping one MView with each source and allows them to travel together (e.g., copying a single CSV plus its dashboard to another project). The centralized .mviews/ folder is useful when a tool wants one discovery root for the whole project, to group all packages, or to keep multiple MViews for the same source. In both cases, each individual package is identified by the .mview suffix.

The same colocated layout can be used for a directory source:

reports/
├── january.csv
├── february.csv
└── notes/
    └── summary.md
reports-summary.mview/
├── mview.json
├── parser.ts
└── Dashboard.tsx

In this case, source.path points to reports/, and source.files contains only the selected relative paths, such as january.csv and notes/summary.md.

Discovery

A conformant runtime discovering MViews for a given file should:

  1. Look for packages matching <workspace>/.mviews/*.mview/mview.json in the centralized location and check each manifest's source.path against the file.
  2. Look for packages matching <source-parent-directory>/*.mview/mview.json next to the source file or directory.
  3. Treat multiple MViews per file as normal and prefer the centralized location for them — a CSV can have both a "Sales Dashboard" and a "Top Clients" view at once.

During convention-based discovery, only directories ending in .mview are considered MView packages. A runtime may explicitly load an mview.json located elsewhere because the schema does not constrain package location, but it must not implicitly discover a directory without the suffix.

For a source with kind: "directory", the runtime should apply the same convention using the source.path directory as the associated source. A directory MView belongs to the directory, not individually to each file in source.files; a tool may also show that relationship when listing the MViews for one of the selected files.

Resolving a directory source

source.path is resolved from the MView directory. Each source.files[].path is then resolved from that source directory. Before reading a file, the runtime MUST check its real resolved path and reject any path or symbolic link that escapes the source directory.

Files that exist under source.path but do not appear in source.files are not part of the MView. Adding a file to the directory does not automatically change the selection or parser input.

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 o directorio desde cualquier lugar. Pero las implementaciones que comparten una convención de descubrimiento interoperan mejor: una herramienta puede listar las MViews de una fuente sin adivinar dónde las puso otra herramienta.

Convención: colocada junto al archivo

Guarda la MView directamente junto al archivo que representa. Cada paquete MView se guarda en un directorio cuyo nombre termina en .mview:

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

Convención: centralizada

O mantén todas las MViews de un workspace dentro de una carpeta centralizada .mviews/, con el source.path de cada manifiesto apuntando de vuelta a su archivo:

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

Cuál usar

Ambas son válidas según la especificación. La ubicación junto al archivo es la opción simple para mantener una MView con cada fuente y permite que ambas viajen juntas (por ejemplo, al copiar un CSV individual junto con su dashboard a otro proyecto). La carpeta .mviews/ centralizada es útil cuando una herramienta quiere una sola raíz de descubrimiento para todo el proyecto, agrupar todos los paquetes o mantener varias MViews para una misma fuente. En ambos casos, cada paquete individual se identifica mediante el sufijo .mview.

Para una fuente de directorio puede usarse la misma colocación:

reportes/
├── enero.csv
├── febrero.csv
└── notas/
    └── resumen.md
resumen-reportes.mview/
├── mview.json
├── parser.ts
└── Dashboard.tsx

En este caso, source.path apunta a reportes/ y source.files contiene únicamente las rutas relativas seleccionadas, por ejemplo enero.csv y notas/resumen.md.

Descubrimiento

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

  1. Buscar paquetes con el patrón <workspace>/.mviews/*.mview/mview.json en la ubicación centralizada y revisar el source.path de cada manifiesto contra el archivo.
  2. Buscar paquetes con el patrón <directorio-padre-de-la-fuente>/*.mview/mview.json junto al archivo o directorio fuente.
  3. Tratar múltiples MViews por archivo como algo normal y preferir para ellas la ubicación centralizada: un CSV puede tener una vista “Sales Dashboard” y una vista “Top Clients” al mismo tiempo.

Durante el descubrimiento por convención, solo los directorios que terminan en .mview se consideran paquetes MView. Un runtime puede cargar explícitamente un mview.json ubicado en otro lugar, ya que el esquema no impone la ubicación del paquete, pero no debe descubrir implícitamente un directorio sin el sufijo.

Para una fuente con kind: "directory", el runtime debería aplicar la misma convención usando el directorio de source.path como fuente asociada. Una MView de directorio pertenece al directorio, no individualmente a cada archivo de source.files; una herramienta puede mostrar esa relación adicional al listar las MViews de uno de los archivos seleccionados.

Resolución de una fuente de directorio

source.path se resuelve desde el directorio de la MView. Cada source.files[].path se resuelve después desde ese directorio fuente. El runtime DEBE comprobar la ruta resuelta real de cada archivo antes de leerlo y rechazar cualquier ruta o enlace simbólico que escape del directorio fuente.

Los archivos que existen bajo source.path pero no aparecen en source.files no forman parte de la MView. Agregar un archivo al directorio no cambia automáticamente la selección ni la entrada del parser.

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.