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

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= — a column attribute: 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, note and link belong to that table; addresses resolve against it.
  • In the file block, only note without an address is allowed: a note about the whole file. An addressed note there is note-address-in-file-block (FAIL); link there is link-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.

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= and type= 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 { is link-template-malformed (WARN).
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, https and mailto (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 link lines on it; a template that referenced it becomes link-unknown-column.
  • Materializing or dematerializing: notes are unaffected; with header=0, renumber index-based col= 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: cell B3 → col= (column B's name) and row= (sheet row − 1 − header rows), or key= when the table has an id column. A threaded comment becomes one note per 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: one link= template; else link="{$}"; else one link per cell (a template plus link lines for exceptions). Internal links are not carried over.
  • Links to .xlsx: every resolved link that passes the scheme check becomes a hyperlink object.

spec/notes.md on GitHub