dashboard is the structure payload schema. It describes dashboard metadata, widget structure, and filter wiring. Data is provided separately through the data schema (DashboardData).

Top-Level Fields

  • id (required): unique dashboard identifier.
  • version: schema version string (default 0.0.1).
  • generated_at / updated_at: timestamps.
  • title / description: dashboard-level text.
  • source: provenance/source system string.
  • tags: free-form tags.
  • timezone: default timezone for display/query context.
  • default_locale: default locale.
  • widgets (required): ordered widget list.

Data Model Capabilities

  • Filter widgets expose a required param_key.
  • Data widgets can consume filters through filter_bindings.
  • Data widgets must use data_ref into DashboardData.data_sources.
  • Numeric chart widgets can specify axis bounds (x_min/x_max, y_min/y_max) to control chart domains.
  • Chart widgets can define semantics like axis scale (x_scale/y_scale), sorting (sort_x), stacking, and secondary y-axis mappings.
  • Widgets can define id; this is required for override-safe workflows when renderconfig.overrides is used.
  • Widget IDs must be unique within a dashboard.

Validation Highlights

  • Unknown widget types are rejected.
  • Unknown fields are rejected (strict schema).
  • Filter bindings must reference declared filter widget param_key values.
  • Data widgets must define data_ref.
  • Inline data payloads are not allowed in dashboard widget definitions.

Example

{
  "id": "sales_dashboard",
  "title": "Sales Overview",
  "source": "warehouse.daily_sales",
  "tags": ["sales", "regional"],
  "timezone": "UTC",
  "default_locale": "en_US",
  "widgets": [
    {
      "type": "date-range-select",
      "id": "date_filter",
      "param_key": "date_range",
      "title": "Date Range"
    },
    {
      "type": "bar-chart",
      "id": "sales_chart",
      "title": "Sales By Region",
      "data_ref": "sales_by_region",
      "filter_bindings": [
        {"param_key": "date_range", "target": "date", "op": "range"}
      ]
    }
  ]
}

Companion Data Payload

{
  "id": "sales_dashboard_data",
  "dashboard_id": "sales_dashboard",
  "data_sources": {
    "sales_by_region": {
      "kind": "inline",
      "data": [
        {"x": "North", "y": 300000},
        {"x": "South", "y": 250000}
      ]
    }
  }
}

Schema Packaging

The dashboard schema is packaged as a primary document plus referenced documents for widget definitions and related types. It is designed for JSON Schema tooling that resolves cross-document references.