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

guide/columns

Columns (column)

This is where guessing ends. One column line per column tells anyone — a person or a tool — what it holds: the type, the unit, the allowed values, what the column is for.

txtab

# column name=id type=long unique=1
# column name=email type=string len-max=254 example=ann@example.com
# column name=amount type=decimal format=0.00 unit=USD

Columns are optional. Describe the three that matter and skip the rest. With a header row, a column is matched to its header cell by name (or title), so the order of column lines doesn't matter. Without a header row, use index= (counting from zero).

name is a plain identifier — Latin letters, digits and underscores (customer_id), the kind every database accepts without quotes. Whatever the header actually says goes into title:

txtab

# column name=amount title="Сумма (руб.)" type=decimal unit=RUB
Сумма (руб.)
1500.00

Type and format

Type What it is
string Text
int / long 32- / 64-bit integer
float / double 32- / 64-bit floating point
decimal Exact decimal — money, no float rounding
boolean true/false (also 1/0)
date / time / datetime ISO 8601
uuid A UUID
binary Base64 bytes

format= is a display hint (format=0.00). example= shows what a value looks like — useful when the data isn't in the file. Make it up; don't copy a real customer's email into the metadata.

Units and money

You write It means
unit=kg, unit=ms, unit=% A unit of measurement
unit=USD Money, in US dollars — any ISO 4217 code in capitals
unit=EUR/kg Euros per kilogram
unit=@cur The unit is in column cur, row by row

The last one is for tables where every row can have its own currency:

txtab

# column name=amount type=decimal unit=@cur role=measure agg=sum
# column name=cur type=string
amount,cur
12.50,EUR
99.00,USD

Tools never add euros to dollars: they group by cur first. And a table total over mixed currencies is left empty, because there isn't one.

Allowed values

Attribute Meaning
enum A closed set: enum=pending|completed|cancelled
pattern A regex the values match
min / max Bounds for numbers and dates
len-min / len-max Bounds for string length
required 1 — never null
unique 1 — values are meant to be unique
default The default a database would use — never filled in when reading

An empty cell reads as null, always — even with default=. The file describes the data as it is.

What a column is for: role and agg

txtab

# column name=order_id type=long role=id
# column name=status type=string role=dimension
# column name=amount type=decimal role=measure agg=sum
# column name=balance type=decimal role=measure agg=avg
# column name=created_at type=datetime role=time
role What you do with it
id count, join — never sum
dimension group by, filter
measure sum, average, min, max
time group by period, trend

agg says how a measure combines: sum for revenue, avg for a balance (never sum balances across months), min/max for highs and lows, none for ratios. A measure without agg sums.

Relations: references

txtab

# table name=orders rows=1200
# column name=customer_id type=long references=customers.id

customer_id points at id in the customers table of the same file — which may come later in the file. It's a map of how tables connect, not a check: nobody validates the values. For keys made of several columns, write the FOREIGN KEY in SQL.

Computed columns

txtab

# column name=price type=decimal
# column name=quantity type=int
# column name=total type=decimal formula="price * quantity"

total isn't stored anywhere — it has no header cell and no field in any row. A tool computes it on demand from price and quantity. Ask a tool to materialize it and the values are written into the data as an ordinary column (materialized=1); dematerialize it to drop them again. The formula stays either way.

Formulas use a small portable language — arithmetic, comparisons, case when, and functions like concat, coalesce, round — so every tool can evaluate them. Anything fancier belongs in a database's generated column, written in SQL.

Everything else

title and description for people, order=asc|desc if the data is sorted, separator= for cells holding several values, link= to make values clickable (Notes and links). Your own attributes start with x-.

guide/columns.md on GitHub