Manifest Reference

Generated from @openislands/schema by scripts/gen-reference.ts. Do not edit by hand. Run pnpm gen:reference to refresh it after a schema change.

A manifest is the typed declaration of a data app: the datasets it reads, the pages and islands that render them, the optional actions and connectors that write to them, and the queries that read from them. This page documents every field the schema accepts. The schema is the single source of truth: the CLI, runtime, and MCP server all validate against it, so an island bound to a field that doesn't exist fails the build and names the island.

Top level

A manifest is a JSON object with the following top-level shape:

{
  "version": 1,                  // required: the manifest format version, always 1
  "title": "Finance Overview",   // required: the app title
  "icon": "wallet",              // optional: the app's tile icon in the workspace app rail
  "datasets": { /* ... */ },     // required: named data sources (see Datasets)
  "pages": [ /* ... */ ],        // required: the app's pages (see Pages)
  "actions": { /* ... */ },      // optional: typed data writes (see Actions)
  "queries": { /* ... */ },      // optional: typed, parameterized reads (see Queries)
  "connectors": { /* ... */ }    // optional: vendored sync integrations (see Connectors)
}

Datasets

datasets maps each dataset name to a source. A dataset is one of three shapes: a file source, a SQL transform, or a SQLite table.

"datasets": {
  "net_worth": { "source": "data/net_worth.csv" },            // a CSV / JSON / Parquet / SQLite file
  "monthly":   { "sql": "models/transforms/monthly.sql" },    // a DuckDB SQL transform over other datasets
  "tracks":    { "source": "data/library.sqlite", "table": "tracks" } // a table within a SQLite database
}

A .sqlite / .db source requires table; supplying table for any other source is a validation error. A sql dataset is derived and read-only; it can never be the target of an action or a connector.

Pages

Each entry in pages is a page: one sidebar entry. A page holds either a flat islands list or tabbed groups, never both:

{
  "id": "overview",       // required: unique page id, used in the URL
  "title": "Overview",    // optional: sidebar label
  "icon": "house",        // optional: one of the curated page icons
  "filters": [ /* ... */ ],  // optional: page-level shared filters (see Page filters)
  "islands": [ /* ... */ ]   // a page has EITHER islands ...
  // "groups": [ { "id": "...", "title": "...", "islands": [ /* ... */ ] } ] // ... OR groups
}

A group is { id, title?, islands }: a string id, an optional title, and its own islands list. Groups render as tabs under the page header, deep-linked via ?group=<id>.

Page filters

A page's optional filters declare shared controls in the page header. Each filter's bind maps each affected dataset to the column the filter applies to; islands whose dataset appears in bind re-query when the filter changes, and the rest ignore it. Two kinds are supported: a daterange over a date column, and a select that narrows a categorical column.

"filters": [
  { "id": "period", "type": "daterange", "label": "Period",
    "bind": { "net_worth": "month", "transactions": "ts" } },
  { "id": "team", "type": "select", "label": "Team", "multiple": true,
    "bind": { "services": "owner" } }
]

Actions

An action is a manifest-declared, typed write into a source dataset (a sql dataset is never writable). mode: "insert" appends rows: an append for a flat file (CSV / JSON(L)), an INSERT for a SQLite table. The row schema is derived from the live data; fields only narrows or annotates it.

"actions": {
  "log_meal": {
    "dataset": "meals",
    "mode": "insert",
    "fields": {
      "meal_type": { "enum": ["breakfast", "lunch", "dinner", "snack"] }
    }
  }
}

A field override (fields.<column>) narrows one column of the derived row schema:

Queries

A query is a manifest-declared, read-only read over one dataset, written as a declarative spec — not raw SQL. The compiler translates it to a parameterized, type-aware SELECT, validates every field against the live columns, and binds every param and value (so it's injection-safe). Its dataset is a source dataset or a sql transform; there are no joins, so heavy shaping lives in a transform the query points at.

"queries": {
  "get_daily_macros": {
    "description": "Macros + goals for one day; omit date for the latest.",
    "dataset": "macros_daily",
    "params": { "date": { "type": "date", "required": false } },
    "where": [{ "field": "date", "op": "eq", "param": "date" }],
    "orderBy": [{ "field": "date", "dir": "desc" }],
    "limit": 1
  }
}

A query param (params.<name>) declares one parameter, referenced by a where clause's param:

A filter (where[]) names a field, an op, and exactly one of param (bind a declared param) or value (a literal). The ops are eq, ne, lt, lte, gt, gte, contains (case-insensitive substring), sameDay (match a timestamp field to a date), and in (a literal value array). A filter bound to an optional param the caller omits is dropped, so the query runs without it.

Connectors

A connector is a vendored integration that syncs a provider's data into source datasets through the same checkpointed write path actions use. The integration code lives in the user's project at <module>/index.ts; the manifest declares an instance:

"connectors": {
  "whoop": {
    "module": "connectors/whoop",                  // connector directory, relative to project root
    "datasets": { "recovery": "whoop_recovery" },  // connector output name → manifest dataset name
    "schedule": "6h",                              // optional: sync interval, overrides the connector default
    "config": { "lookbackDays": 30 }               // optional: validated against the connector's own schema
  }
}

Each datasets value must name a writable source dataset (never a sql dataset), and each key must be one of the connector's declared outputs.

Islands

Each island in a page's islands (or a group's islands) is an object discriminated by its type. Below is every built-in type with its minimum grid span and the fields its config accepts. id, title, and span are common optional fields on every data-bound island; span is a 1–12 grid column count and must not fall below the island's minimum span. Bind an island only to fields that exist in its dataset; a missing field fails validation and names the island.

A layout.row is a structural wrapper: it holds other islands and forces them onto their own full-width grid row. It carries no span, title, or data binding, and it cannot nest another layout.row.

Built-in islands: metric.kpi · metric.scorecard · timeseries.line · category.bar · category.combo · waterfall.bars · breakdown.treemap · distribution.heatmap · activity.calendar · funnel.steps · rank.list · compare.radar · map.choropleth · correlation.scatter · category.pie · table.grid · timeline.feed · gauge.rings · gauge.goal · gauge.meter · status.grid · search.box · note.card · source.doc · content.editor · form.entry

metric.kpi

A single headline number, optionally with a delta vs the previous row or a target — use for at-a-glance KPIs.

Minimum span: 2

metric.scorecard

A compact scorecard of several KPIs off the last row — use for a tidy row of related numbers, each with an optional delta vs the previous row.

Minimum span: 3

timeseries.line

A line chart over time — use for trends; supports multiple y fields, a series split, and a goal line.

Minimum span: 4

category.bar

A bar chart across categories — use to compare discrete groups; supports grouped or stacked bars.

Minimum span: 4

category.combo

A dual-axis chart: bars on the primary axis, lines on a secondary axis — use to compare a level against a rate (revenue vs margin, volume vs price).

Minimum span: 4

waterfall.bars

A waterfall / bridge chart — use for a P&L walk or variance: an opening anchor, signed +/− steps that accumulate, and closing anchors. Mark anchor rows via a kind field whose value is "total".

Minimum span: 4

breakdown.treemap

A treemap of part-to-whole composition — use to show how a total splits across (optionally hierarchical) parts.

Minimum span: 4

distribution.heatmap

A matrix heatmap — use to show one value across two categorical dimensions (x × y), shaded by a continuous color scale.

Minimum span: 4

activity.calendar

A calendar heatmap — use to show a daily value over weeks and months, GitHub-contributions style; rows on the same day sum.

Minimum span: 6

funnel.steps

A funnel of sequential stages — use for conversion or drop-off; each stage's width is its share, ordered by the rows unless sort is set.

Minimum span: 3

rank.list

A ranked Top-N list with proportional bars — use for leaderboards: top products, customers, errors, or movers.

Minimum span: 3

compare.radar

A radar (spider) chart — use to compare entities across several metrics at once; each metric is an axis, each row a polygon.

Minimum span: 4

map.choropleth

A geographic choropleth — use to shade regions (world countries) by a value; region names must match the map's names. Local-first: the map ships as vendored GeoJSON, no network.

Minimum span: 5

correlation.scatter

A scatter or bubble plot of two numeric fields — use to explore correlation; split into series by a field and size points by a third.

Minimum span: 4

category.pie

A pie or donut chart of part-to-whole composition — use for one series' share across a handful of categories; set donut for a hole.

Minimum span: 3

table.grid

A paginated table of raw rows: use when exact values matter; supports column formats, click-to-open details, and collapsible groups.

Minimum span: 5

timeline.feed

A reverse-chronological feed of events: use for logs and activity; supports detail dialogs and collapsible groups, and a rich row layout (header value, inline stats, meta footer) when highlight/stats/footer are set.

Minimum span: 4

gauge.rings

Up to four concentric progress rings read off the last row — use for tracking several goals or budgets at once.

Minimum span: 4

gauge.goal

One ring per goal comparing the last row's value to a goal or target band — use for numbers with a defined good range; within the band reads success-green, under amber, over danger-red. size sets the shared ring footprint so several share a row.

Minimum span: 2

gauge.meter

One or more horizontal usage meters read off the last row — use for quota- or capacity-style values.

Minimum span: 3

status.grid

A responsive grid of state tiles — use for service/check health on ops & status-page dashboards; each tile's tone comes from its state value.

Minimum span: 4

search.box

A search box over a dataset — typing matches rows case-insensitively across fields, results drop down as an autocomplete; selecting a result opens the row's details.

Minimum span: 3

note.card

A static markdown card with no data binding — use for commentary, instructions, or context between islands; set tone to render it as an info/success/warning/danger callout.

Minimum span: 3

source.doc

An embedded file or external link (pdf, markdown, image, link) — use to surface source documents alongside the data; renders as a document card with a type icon, name, and open affordance.

Minimum span: 2

content.editor

A full-page content workspace — browse and edit a directory of markdown files (and CSVs) Obsidian-style, with virtual folders and version history. Set exactly one of file (one doc) or dir (a tree). Binds no dataset and renders full-bleed.

Minimum span: 6

form.entry

A data-entry form card bound to a manifest action — renders one typed input per action field, with a submit button in the bottom-right that inserts a row; the bound dataset's islands then refresh live. The human-facing mirror of the agent's run_action: it reuses the action's typing and so binds no dataset of its own.

Minimum span: 3

Custom islands

When no built-in fits, register a renderer in the user's project under components/custom/<type>/; the directory name is the island type. An unknown island type is accepted as a custom island: with a schema.ts its manifest config is validated by the same machinery that guards the built-ins; without one it renders a placeholder. See the Custom Islands guide for the full shape.