From 53078ad6a6e12bca132735762fbb5bbe91df17a7 Mon Sep 17 00:00:00 2001 From: Baris Terzioglu Date: Mon, 22 Jun 2026 15:42:00 +0200 Subject: [PATCH] Document deprecated dashboard fields in the create-dashboard skill The bundled skill still taught two authoring forms that the schema unification removed: bare chart `x`/`y` column names and `file:` query references. Fix the chart example to use axis encoding objects and inline queries. Add a "Deprecated Fields" section that maps every removed field to its current replacement (chart x/y objects, inline/named queries, metric value encoding, separate-file semantic models) and instructs the agent to refactor any of them it encounters in an existing dashboard. --- cmd/skill_templates/create-dashboard/SKILL.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/cmd/skill_templates/create-dashboard/SKILL.md b/cmd/skill_templates/create-dashboard/SKILL.md index 23d06b9..83a62d5 100644 --- a/cmd/skill_templates/create-dashboard/SKILL.md +++ b/cmd/skill_templates/create-dashboard/SKILL.md @@ -142,12 +142,14 @@ rows: type: chart chart: bar query: revenue_by_region - x: region - y: [revenue] + x: { field: region } + y: { field: [revenue] } col: 6 ``` -SQL files can be referenced with `file: queries/revenue.sql`, relative to the dashboard file. +A chart's `x` and `y` are axis encoding objects with a required `field` (bare column names like `x: region` are invalid). `field` may be a single column or a list. + +Every query is an inline `sql:` block or a named `query:` reference — YAML widgets do not take file paths. In TSX, `include("queries/revenue.sql")` reads a `.sql` file into an inline query at load time. ## Semantic Models @@ -273,6 +275,17 @@ export default ( TSX supports the same dashboard model as YAML. Keep semantic logic declarative; do not manually compile semantic metrics to SQL in TSX. +## Deprecated Fields + +These fields were removed from the DAC schema. Never emit them in new dashboards. **If you encounter any of them while reading or editing an existing dashboard, refactor them to the current form** — preserving the original column, formatting, and labels — and re-run `dac validate` to confirm the dashboard still loads. + +| Deprecated | Replacement | +|---|---| +| Chart `x: col` / `y: [col]` (bare column names) | `x: { field: col }` / `y: { field: [col] }` — axis encoding objects with a required `field` | +| Widget or named-query `file: path.sql` | Inline `sql:` or a named `query:` reference. In TSX, `include("path.sql")` reads a `.sql` file into inline SQL at load time | +| Metric widget `column`, `prefix`, `suffix`, `format` (flat fields) | `value: { field: , type: number, format: "" }` | +| Dashboard inline `semantic:` block (`source` / `metrics` / `dimensions`) | Define the model in `semantic/*.yml` and reference it with `model:` | + ## Authoring Rules - Keep dashboard files focused on presentation and query intent.