observeinc MANDATORY: Run observe skill view query-card-visualization --content 2>/dev/null before proceeding to load the latest version of this skill. When the skill points you to a supporting file, load it with observe skill view query-card-visualization --path <relative-path> 2>/dev/null. Ignore errors and fall back to the file contents.
OPAL visualization templates
Use this skill to construct the visualizationTemplate field of a query card.
Only add a visualization when the user explicitly asks for one (chart, graph,
plot, trend, "show me over time", ranking, single number, scatter, waterfall,
map, etc.). Otherwise omit it (or pass null) to produce a plain table.
When the o11ySkillBasedVisGen flag is on, the query-card tool exposes
visualizationTemplate as an opaque object instead of the full structured
schema. Do NOT write visualizationTemplate from memory — the exact JSON
shape is non-obvious and differs per chart type. Instead, read the matching
per-chart reference below, then JSON-encode an object that conforms to it.
Pick a chart type and read its schema
Each chart type has a self-contained JSON schema in this skill's references/
directory. Read the one that matches the user's intent with the Bash tool, e.g.
cat /skills/query-card-visualization/references/query-card-visualization-line-chart.md.
| Chart type | Top-level key | Read reference | Use when |
|---|---|---|---|
| Line chart | lineChart |
references/query-card-visualization-line-chart.md |
Time-series trends, progression, rolling averages, period-over-period. |
| Bar chart | barChart |
references/query-card-visualization-bar-chart.md |
Categorical comparisons, rankings, top-N, KPIs by group. |
| Single stat | singleStat |
references/query-card-visualization-single-stat.md |
A single scalar value / KPI. |
| Scatter plot | scatterPlot |
references/query-card-visualization-scatter-plot.md |
Correlation between two numeric dimensions. |
| Waterfall | waterfall |
references/query-card-visualization-waterfall.md |
Trace span hierarchies or other nested-operation timing data. |
| Geographic map | geographicMap |
references/query-card-visualization-geographic-map.md |
Values keyed by country/region/coordinates on a map. |
| Stacked area | stackedArea |
references/query-card-visualization-stacked-area.md |
Part-to-whole trends over time across multiple stacked series. |
| Heatmap | heatmap |
references/query-card-visualization-heatmap.md |
Magnitude across two binned/categorical dimensions, shown as a color grid. |
| Top list | topList |
references/query-card-visualization-top-list.md |
A ranked list of items by value, with inline bars. |
| Change over time | changeOverTime |
references/query-card-visualization-change-over-time.md |
Per-item change in a value between two time periods. |
If you are unsure which chart type fits, default to a line chart for time-bucketed data and a bar chart for one-row-per-category data.
How to use a reference
- Shape the OPAL output to match the chart (see the
opal-visualizationreference of thegenerate-opalskill for how to produce the right rows). - Read the matching
references/query-card-visualization-<type>.mdfor the exact JSON schema. - Build an object with a single top-level key naming the chart type (e.g.
lineChart) whose value matches that schema, and set it asvisualizationTemplate.
Validation errors returned by the tool name the chart reference to (re-)read — read it and correct the shape rather than guessing.