• Minimal payloads (no implementation details or derivable properties)
• Easy to diff in Git
• Consistent patterns for GitOps workflows
• Designed for LLM one-shot generation
• Robust validation via OpenAPI spec

Inline vs Saved Object References: When embedding Lens panels in dashboards, prefer inline

attributes

definitions over

savedObjectId

references. Inline definitions are more reliable and self-contained.

title

panels

data

id

meta

spaces

{
  "title": "My Dashboard",
  "panels": [ ... ],
  "time_range": {
    "from": "now-24h",
    "to": "now"
  }
}

Note: Dashboard IDs are auto-generated by the API. The script also accepts the legacy wrapped format

{ id?, data: { title, panels }, spaces? }

and unwraps it automatically.

Target: 8-12 panels above the fold. Use descriptive panel titles on the charts themselves instead of adding markdown headers.

• Eliminate Dead Space: Always calculate the bottom edge (

  y + h

  ) of every panel. When starting a new row or placing a panel below another, its

  y

  coordinate must exactly match the

  y + h

  of the panel immediately above it.
• Align Row Heights: If multiple panels are placed side-by-side in a row (e.g., sharing the same

  y

  coordinate), they should generally have the exact same height (

  h

  ). If they do not, you must fill the resulting empty vertical space before placing the next full-width panel.

esql

{ operation: 'value', column: 'column_name' }

{
  "dataset": {
    "type": "esql",
    "query": "FROM logs | STATS count = COUNT(), avg_bytes = AVG(bytes) BY host"
  }
}

{
  "operation": "value",
  "column": "count"
}

Key Difference: With ES|QL, you write the aggregation in the query itself, then reference the resulting columns. With dataView, you specify the aggregation operation and Kibana performs it.

{
  "type": "metric",
  "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
  "metrics": [{ "type": "primary", "operation": "count", "label": "Total Requests" }]
}

{
  "type": "metric",
  "dataset": { "type": "esql", "query": "FROM logs | STATS count = COUNT()" },
  "metrics": [{ "type": "primary", "operation": "value", "column": "count", "label": "Total Requests" }]
}

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "size": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "line",
      "dataset": {
        "type": "esql",
        "query": "FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
      },
      "x": { "operation": "value", "column": "bucket" },
      "y": [{ "operation": "value", "column": "count" }]
    }
  ]
}

Tip: Always hide axis titles when the panel title is descriptive. Use

bar_horizontal

for categorical data with long labels.

• Dashboard API Reference — Dashboard endpoints and schemas
• Lens API Reference — Lens visualization endpoints
• Chart Types Reference — Detailed schemas for each chart type
• Example Definitions — Ready-to-use definitions

• assets/demo-dashboard.json

  — Complete dashboard with inline Lens panels (dataView format)

• assets/dashboard-with-lens.json

  — Dashboard with ES|QL format (for future reference)

• assets/metric-esql.json

  — Standalone metric visualization

• assets/bar-chart-esql.json

  — Bar chart example

• assets/line-chart-timeseries.json

  — Time series line chart

1. Design for density — Operational dashboards must show 8-12 panels above the fold (within the first 24 rows). Use compact panel heights: metrics MUST be

   h=4

   to

   h=6

   , and charts MUST be

   h=8

   to

   h=12

   .
2. Never use Markdown for titles/headers — Do NOT add

   DASHBOARD_MARKDOWN

   panels to act as dashboard titles or section dividers. This wastes critical vertical space. Use descriptive panel titles on the charts themselves.
3. Prioritize above the fold — Primary KPIs and key trends must be placed at

   y=0

   . Deep-dives and data tables should be placed below the charts.
4. Use descriptive chart titles — Write titles that explain what the chart shows (e.g., "Revenue by Product Category"). Hide axis labels with

   axis.x.title.visible: false

   to reduce clutter
5. Choose the right dataset type — Use

   dataView

   for simple aggregations,

   esql

   for complex queries with joins, transformations, or custom logic
6. Inline Lens definitions — Prefer

   config.attributes

   over

   config.savedObjectId

   for portable dashboards
7. Test connection first — Run

   node scripts/kibana-dashboards.js test

   before creating resources
8. Get existing examples — Use

   lens get <id>

   to see the exact schema for different chart types
9. Avoid redundant metric labels — For ES|QL metrics, avoid using both a panel title and an inner metric label, as it wastes space. Set the panel

   title

   to

   ""

   and configure the human-readable label by aliasing the ES|QL column name using backticks (e.g.,

   STATS `Total Requests` = COUNT()

   and

   "column": "Total Requests"

   ).

{ type: 'dataView', id: '...' }

{ type: 'esql', query: '...' }

metrics: [{ type: 'primary', operation: 'count' }]

metrics: [{ type: 'primary', operation: 'value', column: 'col' }]

{ operation: 'terms', fields: ['host'], size: 10 }

{ operation: 'value', column: 'host' }

{ operation: 'static_value', value: 100 }

EVAL

tag_by: { operation: 'terms', ... }

tag_by: { operation: 'value', column: '...' }

metrics

rows

metrics

rows

{ operation: 'value', column: '...' }

Key Pattern: ES|QL always uses

{ operation: 'value', column: 'column_name' }

to reference columns from the query result. The aggregation happens in the ES|QL query itself.

1. Minimal definitions — Only required properties; defaults are injected
2. No implementation details — No internal state or machine IDs
3. Flat structure — Shallow nesting for easy diffing
4. Semantic names — Clear, readable property names
5. Git-friendly — Easy to track changes in version control
6. LLM-optimized — Compact format suitable for one-shot generation