Dashboard Metadata

A Dashboard defines an analytics page with chart widgets, key metrics, and data visualizations. Dashboards support configurable layouts, global date filters, and auto-refresh.

Basic Structure

Every widget binds to a dataset (the semantic layer, ADR-0021) and selects the dataset's dimensions and values by name. The dataset owns the base object, joins, and measures, so the same numbers stay consistent across every dashboard and report.

const salesDashboard = {
  name: 'sales_overview',
  label: 'Sales Overview',
  description: 'Key sales metrics and pipeline analysis',
  refreshInterval: 300,     // Refresh every 5 minutes

  dateRange: {
    field: 'close_date',
    defaultRange: 'this_quarter',
    allowCustomRange: true,
  },

  widgets: [
    {
      id: 'total_revenue',
      title: 'Total Revenue',
      type: 'metric',
      dataset: 'sales',
      values: ['revenue'],
      layout: { x: 0, y: 0, w: 3, h: 2 },
    },
    {
      id: 'revenue_by_region',
      title: 'Revenue by Region',
      type: 'bar',
      dataset: 'sales',
      dimensions: ['region'],
      values: ['revenue'],
      layout: { x: 3, y: 0, w: 6, h: 4 },
    },
    {
      id: 'deals_by_month',
      title: 'Deals by Month',
      type: 'pie',
      dataset: 'sales',
      dimensions: ['close_month'],
      values: ['deal_count'],
      layout: { x: 9, y: 0, w: 3, h: 4 },
    },
  ],
};

Dashboard Properties

Widgets

Each widget defines a data visualization. A widget binds to a dataset and selects dimensions (X / group / split) and values (the measures to plot):

{
  id: 'monthly_revenue',
  title: 'Monthly Revenue',
  type: 'line',
  dataset: 'invoicing',
  dimensions: ['invoice_month'],
  values: ['paid_total'],
  filter: { status: 'paid' },
  layout: { x: 0, y: 0, w: 6, h: 4 },
}

Widget Properties

Widget options

options is an open bag: keys the renderer understands (icon, columns, striped, density, …) pass through untouched. Five keys are declared, because they are not presentation-only — four of them change the query the dataset compiles to:

Because they are declared, a misspelling (sortDirection, granularity) is an author-time error rather than an option that reads as if it works.

{
  id: 'revenue_trend',
  type: 'area',
  dataset: 'opportunity_metrics',
  dimensions: ['close_date'],
  values: ['total_amount'],
  // Group by month rather than by raw timestamp.
  options: { dateGranularity: 'month' },
}

Notes on behaviour:

• sortBy must name something the widget selects; the server rejects an order key it cannot resolve rather than ignoring it.
• A limit with no sortBy orders by the selected dimensions first, so it truncates a reproducible window instead of an arbitrary subset.
• Ordering is applied to the finished grid, so a derived measure is a valid sortBy even though no single SQL statement computes it.
• A sortBy naming a select or lookup dimension orders by the display label the rows render (the option label / the related record's name), not the stored value or foreign-key id — and the label is resolved before limit applies, so a top-N by name truncates the right N. Sorting by a measure (the common case) involves no label lookup and is unaffected.
• A funnel with no declared stage order falls back to sorting by value descending.

Datasets

Every widget binds to a dataset — the single semantic layer (ADR-0021). A dataset defines the base object, allowed relationship joins, reusable dimensions, measures, and intrinsic filters once; dashboards and reports then reference the same names so "revenue", "pipeline", or "win rate" stay consistent across surfaces.

The legacy inline-query shape (object + categoryField + valueField + aggregate directly on the widget) was removed in the ADR-0021 single-form cutover. Define a dataset and bind widgets to it instead.

import { defineDataset } from '@objectstack/spec/ui';

export const salesDataset = defineDataset({
  name: 'sales',
  label: 'Sales',
  object: 'opportunity',
  include: ['account'],
  dimensions: [
    { name: 'region', field: 'account.region', type: 'string' },
    { name: 'close_month', field: 'close_date', type: 'date', dateGranularity: 'month' },
  ],
  measures: [
    { name: 'revenue', field: 'amount', aggregate: 'sum' },
    { name: 'deal_count', aggregate: 'count' },
  ],
});

export const salesDashboard = {
  name: 'sales_overview',
  label: 'Sales Overview',
  widgets: [
    {
      id: 'revenue_by_region',
      title: 'Revenue by Region',
      type: 'bar',
      dataset: 'sales',
      dimensions: ['region'],
      values: ['revenue'],
      layout: { x: 0, y: 0, w: 6, h: 4 },
    },
  ],
};

Each widget requires a dataset and at least one values entry. The widget's dimensions and values must reference names declared on the bound dataset.

At runtime, dataset queries are executed through the analytics service. When @objectstack/plugin-security is registered, analytics auto-bridges to security.getReadFilter(object, context) and applies the caller's RLS scope to the base object and joined objects.

ObjectUI currently renders dataset-backed metric, chart, table/list, pivot, funnel, and gauge-style widgets with type-aware cells, field/option labels, date bucketing, and numeric/currency formatting. table and pivot widgets are also drill-through (see Drill-down below); the dataset preserves raw group keys so the generated filter navigates to the exact underlying records.

Chart Types

Additional types: horizontal-bar, column, donut, sankey, solid-gauge, kpi, and bullet. The default type is metric.

Drill-down

table and pivot widgets are drill-through: clicking an aggregated row (table) or cell (pivot) opens a side drawer listing the underlying records behind that group. Because the dataset preserves each grouped row's raw group keys, the drawer's filter matches the exact records — no label-to-id guessing.

The drilled record list is itself drill-to-record: click any row in the drawer to open that single record's detail. This completes the group → records → record chain (e.g. Revenue by Region → the orders in the West bucket → one order).

The drawer also offers an "Open in list →" escape hatch — escalate the peek to the object's full list page (sort / bulk-select / export / shareable URL), scoped by the same drill filter. In-place drawer is the default (keep context); the escape hatch is there when you need the full surface. Reports drill identically: a summary / matrix report opens the same in-place drawer on row/cell click, so dashboard and report drill behave the same.

// A drill-through table widget. No drill configuration is required — it is
// automatic whenever the dataset exposes the base object and the widget groups
// by at least one dimension.
{
  id: 'orders_by_region',
  title: 'Orders by Region',
  type: 'table',
  dataset: 'sales',
  dimensions: ['region'],
  values: ['revenue', 'deal_count'],
  layout: { x: 0, y: 0, w: 6, h: 4 },
}

Drill-through is automatic — there is no per-widget drill configuration in the dataset form. metric and chart widgets render the aggregate only and are not click-drillable; expose the detail through a table/pivot widget instead.

Renderer note. Object/record-backed list and table surfaces (and the ObjectUI renderer's options.drillDown block) support a richer drill model — a mode: 'filter' | 'record' discriminator, a target of 'drawer' / 'dialog' / 'navigate' (the last opens the list page directly), a column whitelist, and chart-segment drill for the scatter / treemap / sankey families. Those knobs live in the renderer; dataset-bound dashboards drill through the semantic layer as described above (and get the "Open in list →" escape hatch from the host app, e.g. the console).

Aggregation Functions

Aggregation is declared on the dataset's measures (via aggregate), not on the widget. Supported functions:

Widget Layout

Widgets are positioned on a 12-column grid:

layout: {
  x: 0,    // Column position (0-11)
  y: 0,    // Row position
  w: 6,    // Width in columns (1-12)
  h: 4,    // Height in rows
}

Date Range

Configure a global time filter that applies to all widgets:

dateRange: {
  field: 'created_at',
  defaultRange: 'this_month',
  allowCustomRange: true,
}

Preset Ranges

The thirteen named ranges are published as DATE_RANGE_PRESETS in @objectstack/spec/ui — the vocabulary's single source of truth. custom is not one of them: it selects no window, it opens the picker.

Global Filters

Add interactive filter controls that apply to all widgets:

globalFilters: [
  { name: 'region', field: 'region', label: 'Region', type: 'select' },
  { field: 'owner', label: 'Sales Rep', type: 'lookup' },
]

Each filter's name is its stable identity: the key its value is published under as a dashboard-level variable (readable in widget expressions as page.<name>) and the key widgets reference in filterBindings. It defaults to field; the name dateRange is reserved for the built-in date range.

Date Filter Defaults

A type: 'date' filter's defaultValue must be a value the dashboard can actually resolve to a window. Three spellings qualify:

globalFilters: [
  { field: 'created_at', label: 'Date Range', type: 'date', defaultValue: 'last_7_days' },
]

Anything else is rejected at author time. This matters because the failure it replaces was silent: an unrecognised name cannot be lifted to a range, so it fell through to "a bare string date means equality on that day" and produced created_at = 'last_7_dayz' — a condition no row matches, which the backend answers 200 OK with a zero. Every tile read 0 while the filter bar showed "All time", so the dashboard looked deliberately empty rather than misconfigured.

custom is not accepted here. It is a dateRange.defaultRange sentinel meaning "open the picker with no preset applied", and a bare filter value gives it no from/to to hand over.

Per-Widget Filter Bindings

By default a filter applies to its own field on every widget (the date range defaults to dateRange.field ?? 'created_at'). When a widget stores the concept under a different field — or should ignore a filter — declare filterBindings on the widget:

widgets: [
  // Default binding: dateRange → created_at, region → region.
  { id: 'invoices_by_status', /* … */ },
  // This widget's own fields differ — map each filter explicitly.
  {
    id: 'accounts_signed',
    filterBindings: { dateRange: 'signed_at', region: 'sales_region' },
    /* … */
  },
  // Opt out of a filter with `false`.
  { id: 'total_invoices', filterBindings: { region: false }, /* … */ },
]

Binding precedence: an explicit filterBindings entry (string override or false opt-out) → the filter's legacy targetWidgets allow-list → the filter's own field.

Complete Example

First define the dataset the widgets bind to:

import { defineDataset } from '@objectstack/spec/ui';

export const projectTasksDataset = defineDataset({
  name: 'project_tasks',
  label: 'Project Tasks',
  object: 'project_task',
  dimensions: [
    { name: 'status', field: 'status', type: 'string' },
    { name: 'priority', field: 'priority', type: 'string' },
    { name: 'completed_month', field: 'completed_at', type: 'date', dateGranularity: 'month' },
  ],
  measures: [
    { name: 'open_count', aggregate: 'count', filter: { status: { $ne: 'done' } } },
    { name: 'done_count', aggregate: 'count', filter: { status: 'done' } },
    { name: 'task_count', aggregate: 'count' },
  ],
});

Then bind the dashboard widgets to it:

const projectDashboard = {
  name: 'project_overview',
  label: 'Project Overview',
  description: 'Real-time project health metrics',
  refreshInterval: 60,

  dateRange: {
    field: 'created_at',
    defaultRange: 'this_month',
    allowCustomRange: true,
  },

  globalFilters: [
    { field: 'project', label: 'Project', type: 'lookup' },
    { field: 'assignee', label: 'Team Member', type: 'lookup' },
  ],

  widgets: [
    {
      id: 'open_tasks',
      title: 'Open Tasks',
      type: 'metric',
      dataset: 'project_tasks',
      values: ['open_count'],
      layout: { x: 0, y: 0, w: 3, h: 2 },
    },
    {
      id: 'completed_this_week',
      title: 'Completed This Week',
      type: 'metric',
      dataset: 'project_tasks',
      values: ['done_count'],
      layout: { x: 3, y: 0, w: 3, h: 2 },
    },
    {
      id: 'tasks_by_status',
      title: 'Tasks by Status',
      type: 'pie',
      dataset: 'project_tasks',
      dimensions: ['status'],
      values: ['task_count'],
      layout: { x: 6, y: 0, w: 3, h: 4 },
    },
    {
      id: 'tasks_by_priority',
      title: 'Tasks by Priority',
      type: 'bar',
      dataset: 'project_tasks',
      dimensions: ['priority'],
      values: ['task_count'],
      layout: { x: 9, y: 0, w: 3, h: 4 },
    },
    {
      id: 'completion_trend',
      title: 'Completion Trend',
      type: 'line',
      dataset: 'project_tasks',
      dimensions: ['completed_month'],
      values: ['task_count'],
      layout: { x: 0, y: 4, w: 12, h: 4 },
    },
  ],
};

Related

• App Metadata — Reference dashboards in app navigation
• View Metadata — List views for record browsing
• Page Metadata — Custom pages with component layouts