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

spec/metadata

Metadata (meta-*)

txtab

P meta-source sales_db.orders
P meta-as-of 2026-11-01
P meta-comment-truncated
  • The keyword is meta-<key>; <key> is kebab-case ([a-z][a-z0-9-]*).
  • The payload is raw text to end of line, taken as-is: no quoting, no escaping. Leading and trailing spaces of the payload are not significant.
  • An empty payload makes the line a flag: its value is its presence.
  • In the file block, metadata describes the file; in a table block, it describes that table. A table inherits nothing from the file block — a reader that wants both looks at both.
  • Each key is unique per block. On a repeat the last line wins (meta-duplicate, WARN).
  • Any key MAY be used. Unknown keys are preserved or ignored, never an error.

Conventional keys

Keyword Meaning Example
meta-source Origin system, table or file (provenance, not a path — use reference= for data files) P meta-source sales_db.orders
meta-author Creator name or contact P meta-author alex@example.com
meta-comment Free-text description of the dataset P meta-comment demo dataset
meta-grain What one data row represents P meta-grain one row per order
meta-created When the file was written (ISO 8601) P meta-created 2026-03-24T12:00:00Z
meta-exported When the data was exported (ISO 8601) P meta-exported 2026-03-24T14:30:00Z
meta-as-of The date or date-time the data is current as of (ISO 8601) P meta-as-of 2026-11-01
meta-license Data license identifier P meta-license CC-BY-4.0
meta-tool Tool and version that wrote the file P meta-tool txtab/0.1.0
meta-tags Comma-separated tags P meta-tags sales,Q1,2026
meta-comment-truncated Flag, archive comment only: the comment is truncated (archive.md) P meta-comment-truncated

meta-grain

Free text describing the unit of one data row: one row per order, one row per customer per day, pre-aggregated monthly totals. Descriptive only.

meta-as-of

The moment the data reflects — not when the file was written (meta-created) or exported (meta-exported). A snapshot taken on 1 November and exported on 3 November has meta-as-of 2026-11-01 and meta-exported 2026-11-03T….

meta-comment-truncated

Written only into the ZIP comment of a .txtab.zip (archive.md). In a .txtab file it has no meaning and MUST be ignored.

spec/metadata.md on GitHub