[0.1 draft] [guide 15 · spec 15 pages]

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.
  • color with stack=0 (or absent) draws grouped bars; stack=1 stacked; stack=normalize 100%-stacked.
  • type=bar bin=<n> x=<measure> y=count() is a histogram.
  • point/circle with both x and y is 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.

spec/charts.md on GitHub