spec/notes
Notes and links (note, link, link=)
note— a remark on a cell, a row, a column, the table, or the whole file.link=— acolumnattribute: a URL template that makes every value of the column a link.link— a URL on one cell, for links that don't follow the column's template.
All three are optional and advisory. A note or link is never part of a value: it does not affect aggregates, formulas or rows=, and is never read as data.
Syntax
note and link are key-value lines, tokenized like the first line (first-line.md); values with spaces are quoted, " inside is "". Single line only. A line that does not tokenize: note-malformed / link-malformed (FAIL). Unknown attributes are ignored; custom ones use x-.
txtab
P note row=2 col=amount author=alex@example.com created=2026-03-24T12:00:00Z text="Refund pending, see ticket 1234"
P link key=1042 col=invoice href="https://billing.example.com/inv/A-77"Scope
- In a table block,
noteandlinkbelong to that table; addresses resolve against it. - In the file block, only
notewithout an address is allowed: a note about the whole file. An addressednotethere isnote-address-in-file-block(FAIL);linkthere islink-in-file-block(FAIL). - A note spanning several tables is not defined.
Addressing
| Attribute | Value | Meaning |
|---|---|---|
col |
column name; zero-based index when header=0 |
Column (same rule as column name= / index=) |
row |
non-negative integer | Data record, zero-based, not counting the header row |
key |
text | The row's value in the table's id column — an alternative to row |
Setting both row and key is note-row-and-key / link-row-and-key (FAIL).
The id column
key= resolves against the table's id column: the single column with role=id; if there is none, the single column with unique=1. With no candidate, or several at the deciding step, the table has no id column and every key= in it is unresolved.
key= matches a record whose id value, as raw text after CSV unquoting, equals the key= value exactly — no type coercion (key=007 does not match 7). A null never matches. With several matches, the first wins.
row= is positional and breaks when rows are reordered; key= survives sorting and filtering, including by tools that know nothing about Text Tables. Writers SHOULD use key= when the table has an id column.
note
| Attribute | Requirement | Meaning |
|---|---|---|
text |
MUST (note-missing-text, FAIL) |
The note, plain text |
col, row, key |
MAY | Address |
author |
MAY | Who wrote it, typically an email address |
created |
MAY | When, ISO 8601 date-time |
| Address | Attached to |
|---|---|
row/key + col |
one cell |
col only |
a column |
row/key only |
a row |
| none, in a table block | the table |
| none, in the file block | the file |
Any number of notes may share a target; consumers MUST preserve their file order. No replies, threads or resolved state. text has no markup.
link= on column
txtab
P column name=order_id type=int role=id link="https://crm.example.com/orders/{$}"
P column name=customer type=string link="https://crm.example.com/c/{customer_id}"
P column name=homepage type=string link="{$}"The displayed value stays the cell's own value; link= only says where it points.
| Token | Substituted with |
|---|---|
{$} |
the current cell's value |
{name} |
the value of column name in the same row |
{N} |
the value at zero-based index N — header=0 only |
{{ |
a literal { |
- Placeholders take the raw value after CSV unquoting;
format=,unit=andtype=do not apply. - Each substituted value MUST be percent-encoded as UTF-8 with uppercase hex, leaving only RFC 3986 unreserved characters (
A–Z a–z 0–9 - . _ ~). Exception: a template that is exactly one placeholder (link="{$}",link="{url}") substitutes without encoding — the value is the URL. - A null placeholder value means the cell has no link.
- A placeholder MUST name a stored or materialized column of the same table; otherwise
link-unknown-column(WARN, the column is shown without links). An unterminated{islink-template-malformed(WARN).
link
| Attribute | Requirement | Meaning |
|---|---|---|
href |
MUST (link-missing-href, FAIL) |
The URL, used as is (not a template) |
col |
MUST | Column of the cell |
row / key |
MUST, exactly one | Row of the cell |
Missing col, or missing both row and key: link-missing-address (FAIL). A link overrides the column's link= for its cell. Two link lines on one cell: last wins (link-duplicate, WARN).
Resolution
An address that does not resolve — unknown col, row past the last record, key with no match or no id column — is note-unresolved / link-unresolved (WARN). Such lines MUST be preserved on round-trip so a later fix can resolve them.
For a reference= or storage=columns table, addresses resolve against the external data; a parser that has not opened it reports nothing.
Safety
Link templates and href values from an untrusted file are untrusted input.
- Consumers MUST NOT fetch or follow links on their own.
- The scheme MUST be checked on the final URL, after substitution. Only
http,httpsandmailto(case-insensitive) MAY be rendered as links; anything else, or no scheme, is shown as plain text (link-unsafe-scheme, WARN). - Exporting to
.xlsx, writers MUST emit hyperlink objects and MUST NOT emit=HYPERLINK(...)formulas. - HTML renderers MUST escape both the displayed value and the URL.
Writer obligations
- Reordering or removing rows: update every
row=; drop lines whose row was removed.key=lines change only when their row was removed (dropped). - Renaming a column: update
col=and every{name}that refers to it. - Removing a column: drop notes and
linklines on it; a template that referenced it becomeslink-unknown-column. - Materializing or dematerializing: notes are unaffected; with
header=0, renumber index-basedcol=and{N}if positions shift.
note and link are for the handful of remarks a person actually leaves; a per-row status is a column, not a note. Writers SHOULD keep them to a few KiB per table.
Excel interop (informative)
- Notes from
.xlsx: cellB3→col=(column B's name) androw=(sheet row − 1 − header rows), orkey=when the table has an id column. A threaded comment becomes onenoteper message, in order; reply structure and resolved state are dropped. - Notes to
.xlsx: cell notes become classic notes; several on one cell are joined, one line each. Column-, row-, table- and file-level notes have no Excel equivalent; a tool MAY pin them to a header cell or list them on a separate sheet. - Links from
.xlsx: per column, the most compact exact form: onelink=template; elselink="{$}"; else onelinkper cell (a template pluslinklines for exceptions). Internal links are not carried over. - Links to
.xlsx: every resolved link that passes the scheme check becomes a hyperlink object.