spec/charts
Charts (chart)
A table MAY carry chart suggestions: declarative hints that some of its declared columns are meant to be viewed together in a specific way. chart is optional and advisory; a consumer that ignores it still has a valid file. It states a relation between columns ("amount by category, as bars"), not a task for a consumer to execute.
Syntax
Compact form — a key-value line:
txtab
P chart type=<mark> name=<identifier> <channel>=<column> [<channel>=<column> …] [<modifier>=<value> …]Escape hatch — chart-<engine> with raw text to end of line:
txtab
P chart-vega <Vega-Lite unit-spec JSON>For what the compact form can't express (facets, layered views, selections). vega is the only defined engine; another chart-<engine> MUST be ignored by parsers that don't implement it (chart-unknown-type, WARN). A chart-vega payload that is not valid JSON is chart-vega-invalid-json (FAIL).
Scope
chart and chart-<engine> live in a table block; channels resolve against that table's columns. In the file block they are chart-in-file-block (FAIL). Charts spanning several tables are not defined.
Required attributes
| Attribute | Meaning | Missing |
|---|---|---|
type |
The mark | chart-missing-type, FAIL |
name |
Identifier of this suggestion, unique within the table | chart-missing-name, FAIL |
A duplicate name within a table is chart-duplicate-name (WARN); the last line wins for addressing.
type — mark
type |
Vega-Lite mark | Typical use | Required channels |
|---|---|---|---|
bar |
bar |
Bar chart | x, y |
line |
line |
Trend over time | x, y |
area |
area |
Area under a line | x, y |
point |
point |
Scatter, or one-axis distribution | x, y (or one of them) |
circle |
circle |
Filled-dot scatter | x, y |
arc |
arc |
Pie / donut | theta |
rect |
rect |
Heatmap | x, y, color |
tick |
tick |
Values on one axis | x or y |
boxplot |
boxplot |
Distribution | x or y + value |
text |
text |
Labels as marks | x, y, text |
sparkline |
— | Compact trend, no axes | y |
A missing required channel is chart-missing-required-channel (FAIL). An unknown type MUST be ignored and preserved on round-trip (chart-unknown-type, WARN).
Channels
Each channel takes a column name (never an index). Every referenced column MUST have a column name= line in the same table (chart-unknown-column, FAIL).
| Channel | Meaning |
|---|---|
x, y |
Primary axes |
x2, y2 |
Second bound of a range |
color |
Split by color |
size |
Point size / stroke width |
theta |
Arc angle (pie slice) |
radius |
Arc radius |
shape |
Marker shape |
opacity |
Opacity |
column, row |
Facets |
detail |
Extra grouping without a visual channel |
order |
Point order on line/area (default x) |
tooltip |
Column(s) shown on hover, comma-separated |
text |
Label column for type=text |
The channel's encoding type (nominal, ordinal, quantitative, temporal) is inferred from the column's type and role. count() is a reserved value usable wherever a channel expects a column: the number of rows (y=count()). Unknown channels or modifiers: chart-unknown-channel (WARN).
Modifiers
| Attribute | Value | Meaning |
|---|---|---|
title |
quoted text | Chart title |
aggregate |
sum, avg, min, max, count, count-distinct |
Overrides the column's agg= for this chart only |
bin |
0, 1, or integer ≥ 2 |
Bucket a continuous value: 0 off, 1 on with 10 bins, n bins |
stack |
1, 0, normalize |
Stacking for bar/area with color |
sort |
asc, desc, or a column name |
Category order |
limit |
integer ≥ 1 | Top-N after sort |
hole |
0.0–1.0 |
Donut hole on type=arc |
Modifiers apply to their chart line only and never change the column's own attributes. An out-of-range value (bin=-3, limit=0) is not a parse error; a renderer SHOULD decline to draw that chart with a message naming the attribute.
Orientation and variants
x=<dimension> y=<measure>draws vertical bars;x=<measure> y=<dimension>horizontal.colorwithstack=0(or absent) draws grouped bars;stack=1stacked;stack=normalize100%-stacked.type=bar bin=<n> x=<measure> y=count()is a histogram.point/circlewith bothxandyis a scatter; with one of them, a one-axis distribution.
Examples
txtab
P column name=category type=string role=dimension
P column name=amount type=decimal role=measure agg=sum unit=USD
P column name=region type=string role=dimension
P column name=date type=date role=time
P chart type=arc name=spend_by_category theta=amount color=category title="Spend by category"
P chart type=bar name=top_categories x=category y=amount sort=desc limit=10
P chart type=bar name=spend_by_region x=region y=amount color=category stack=1
P chart type=line name=amount_over_time x=date y=amount
P chart type=bar name=amount_histogram bin=20 x=amount y=count()
P chart type=sparkline name=amount_trend y=amount
P chart-vega {"mark":"arc","encoding":{"theta":{"field":"amount","aggregate":"sum","type":"quantitative"},"color":{"field":"category","type":"nominal"}}}Rendering (informative)
A tool MAY provide txtab chart FILE [--table T] [--name N] that resolves channels, pre-aggregates per the modifiers, and renders the chart as monospace text — for terminals, CI logs, diffs and LLM context. Nulls are skipped as in aggregates.md; a group with no values has no sum/avg/min/max (not 0), while counts of such a group are 0. On line and area a missing value MUST be drawn as a gap, never as 0.
The spec shape {"chartType", "title", "labels", "series": [{"values"}]} is compatible with asciicharts:
type |
asciicharts chartType |
|---|---|
bar |
vbar / hbar by orientation; grouped/stacked by stack |
bar with bin |
histogram |
line, area |
line, area |
point, circle |
scatter (two channels) / dotplot (one) |
arc |
pie (hole may be ignored) |
rect |
heatmap |
boxplot, sparkline |
boxplot, sparkline |
tick, text |
no equivalent |
A renderer MAY implement a subset of marks and modifiers. What it cannot draw is a capability gap, not a file defect: it SHOULD degrade gracefully (print the title and columns, or skip) and MUST NOT fail the file.