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 grid span range 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 that must sit within the island's min–max range (a value below min or above max is a named validation error), and defaults to the recommended width when omitted. Compact, single-value islands cap well below full width; data-dense ones run the full 12. 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 · divergence.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 · board.kanban

metric.kpi

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

Span: min 2, recommended 4, max 6 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 3, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

timeseries.line

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

Span: min 4, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

category.bar

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

Span: min 4, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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

Span: min 4, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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

Span: min 4, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

divergence.bars

A diverging bar chart: one signed bar per category extending above or below a zero baseline, optionally colored by which value band it falls into. Use for deviation from a reference — daily calorie surplus/deficit, budget variance, net cash flow, sentiment, temperature anomaly. Pick this over category.bar when values are signed and the up/down direction is the message, and over waterfall.bars when each bar stands on its own rather than accumulating into a running total.

Span: min 4, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

breakdown.treemap

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

Span: min 4, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

distribution.heatmap

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

Span: min 4, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

activity.calendar

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

Span: min 6, recommended 12, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 3, recommended 4, max 6 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

rank.list

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

Span: min 3, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

compare.radar

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

Span: min 4, recommended 6, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 5, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 4, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 3, recommended 4, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

table.grid

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

Span: min 5, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 4, recommended 7, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

gauge.rings

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

Span: min 4, recommended 5, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 2, recommended 5, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

gauge.meter

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

Span: min 3, recommended 4, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 4, recommended 8, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 3, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 3, recommended 6, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 2, recommended 4, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.

Span: min 6, recommended 12, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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 runActions insert: it reuses the action's typing and so binds no dataset of its own.

Span: min 3, recommended 5, max 8 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

board.kanban

A full-bleed kanban board grouping rows into columns by a status/stage field — use for work queues, incidents, or pipeline stages. Pick this over table.grid / status.grid when cards should move between columns, and over form.entry when the interaction is reassigning an existing row rather than inserting one. Moving a card POSTs match+set through the bound update action; without action or with readOnly, the board is view-only.

Span: min 6, recommended 12, max 12 (of 12). Omit span to render at the recommended width; below min or above max is a named error.

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.