The dashboard language

*.diver.yml files define dashboards as versioned resources that can be previewed locally and published to a Diver workspace.

The file is meant to live next to the code, models, or dbt project that explains the data. It gives teams a repeatable way to review dashboard changes before they become workspace dashboards.

Resource Names

Every resource_name in a *.diver.yml file is stable, human-readable, and used by Diver to update the same resource on the next preview or publish.

Resource names are not database IDs. Changing a resource name tells Diver to create or target a different resource.

Source resource names are read-only from the CLI. Create or rename sources in the web app, then use diver sources to list the source resource names available to your workspace:

diver sources

Example

version: 1
resource_name: sales-analytics
name: Sales Analytics

dashboards:
  - resource_name: management-overview
    name: Management Overview
    dimensions: { width: 12, height: 10 }
    charts:
      - resource_name: leads-created
        title: Leads created
        visualization: bar
        position: { x: 1, y: 1 }
        size: { width: 4, height: 3 }
        dataset:
          label: Leads
          type: bar
          source: warehouse-prod
          query: |
            select count(*) as leads from data.leads

Top-level fields

Field	Required	Description
version	Yes	The resource file version. Use 1.
resource_name	Yes	The resource name for this dashboard package. Preview groups are matched by this value.
name	Yes	The display name shown in Diver.
dashboards	Yes	A list of dashboards to preview or publish.

Dashboard fields

Field	Required	Description
resource_name	Yes	Stable resource name for the dashboard. Publishing the same resource name updates the same dashboard.
name	Yes	Dashboard title.
dimensions.width	No	Number of grid columns. Defaults to 12 when omitted.
dimensions.height	No	Number of grid rows. Defaults to 12 when omitted.
cache_ttl	No	Cache duration in seconds.
charts	Yes	Charts to place on the dashboard. Use an empty list for a dashboard without charts.

Chart fields

Field	Required	Description
resource_name	Yes	Stable resource name for the chart within the dashboard.
title	Yes	Chart title.
visualization	Yes	Visualization type, such as table, bar, or another type supported by the workspace.
position.x	Yes	Left grid position.
position.y	Yes	Top grid position.
size.width	Yes	Chart width in grid columns.
size.height	Yes	Chart height in grid rows.
dataset	No	Dataset definition for the chart. If omitted, existing datasets for the chart are removed on the next import.

Dataset fields

Field	Required	Description
label	Yes	Dataset label shown in the chart configuration.
type	Yes	Dataset rendering type. This often matches the chart visualization.
source	Yes	Source resource name from Diver, for example warehouse-prod.
query	Yes	Diver query or SQL text to run for the dataset.
render_settings	No	Visualization-specific settings.

Preview and publish behavior

diver preview creates or updates dashboards in your personal preview dashboard group. Preview dashboards are private to you unless the preview group is shared.

diver publish creates or updates workspace dashboards. Published dashboards are matched by dashboard resource_name and can be added to normal dashboard groups for sharing.

Naming guidance

Use short, descriptive resource names that can survive display-name changes:

resource_name: revenue-operations

Avoid environment-specific or personal names in published resources. Prefer stable source names such as warehouse-prod, stripe, or hubspot.