Text Tables — the guide
Plain text tables that describe themselves. These pages are for anyone who works with tables — analysts, data engineers, anyone who opens a .csv and wishes it came with a note explaining what's inside. They cover what you can put in a file, what it means, and why it's worth it.
| Topic | What it gives you |
|---|---|
| Introduction | The idea in two minutes: context that travels with the data |
| File structure | How a file is laid out: first line, blocks, tables; choosing a prefix |
| First line | The one line that names the format and the dialect |
| System lines | A map of every keyword so you know what you're looking at |
| Tables | One table or several; data inline, in a CSV next door, or column by column |
Metadata (meta-*) |
Source, author, grain, as-of date, license |
Columns (column) |
Types, units and money, allowed values, roles, relations, computed columns |
Aggregates (agg-*) |
Totals and counts that ride along — trustworthy without scanning |
SQL (sql-*) |
Ship the CREATE TABLE, the keys and the query with the data |
| Notes and links | Leave a remark on a cell, row, column or file; turn values into links |
Charts (chart) |
Suggest a bar, line or pie over columns you've described |
Archives (.txtab.zip) |
Zip it, preview the schema without unzipping, store wide tables by column |
| Full example | One file showing most features at once |
| Prior art | Where the ideas come from, and how Text Tables compares |
Building a tool, parser or validator? The precise rules — required fields, edge cases, the error-code registry — are in ../spec/. This guide leaves them out so it stays readable; the spec wins when the two differ.