Comparison Table Kind — Specification
Purpose
Presents a matrix of items (rows) evaluated against criteria (columns). Each cell value is declared inline within the row entry.
TOML Schema
kind = "comparison"
title = <string>? # optional diagram title
[[columns]]
label = <string> # evaluation criterion (required, unique)
[[rows]]
label = <string> # item being compared (required, unique)
<ColumnLabel> = <string> # cell value for that column (optional, omit = empty cell)
Constraints
| Constraint | Rule |
|---|---|
| Rows | 1–10 |
| Columns | 1–8 |
| Column label | Must not be "label" (reserved for the row identifier) |
| Cell keys in rows | Must match a declared columns[].label; unknown keys are an error |
| Missing cells | Treated as empty (allowed) |
Rendering Specification
- Canvas: 800px wide, height = title_area + 45px column header + rows × 50px + 20px padding
- Row header column: 180px wide, apex-tinted background
- Column header row: 45px tall, apex color background, bold white/dark text
- Data cells: 50px tall, equal width distributing remaining canvas; alternating even/odd row backgrounds
- Grid borders: 1px lines using apex-background interpolated color
- Text: Noto Sans, 13px; truncated with
…if wider than available cell width
Example
Example Files
valid/basic.toml— 2 rows × 2 columns, inline cellsvalid/no_title.toml— title omittedvalid/empty_cells.toml— no cells defined (sparse table)valid/basic.json— JSON formatinvalid/no_rows.toml— missing rows → errorinvalid/no_columns.toml— missing columns → errorinvalid/invalid_cell_ref.toml— row uses undeclared column key → errorinvalid/too_many_columns.toml— 9 columns exceeds limit → error
Label capacity
How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.
A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
columns[].label | 2 columns, 2 rows | 21 / 21 | 40 / 40 |
rows[].label | 2 columns, 2 rows | 12 / 12 | 23 / 23 |
rows[].<column> | 2 columns, 2 rows | 21 / 21 | 40 / 40 |
Schema
What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | comparison |
title | string | no |
columns — 1 to 8 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes |
rows — 1 to 10 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
<column> | string | no | one key per declared column, named by the column's label; its value is the cell |
Rules
- a column is not labelled
label(the row field uses that name) - a row has no key that is not a declared column