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

ConstraintRule
Rows1–10
Columns1–8
Column labelMust not be "label" (reserved for the row identifier)
Cell keys in rowsMust match a declared columns[].label; unknown keys are an error
Missing cellsTreated 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

JavaScript Framework Comparison Comparison of React, Vue by Performance, Ecosystem. React: Performance ★★★★, Ecosystem ★★★★★; Vue: Performance ★★★★, Ecosystem ★★★. JavaScript Framework Comparison Performance Ecosystem React Vue ★★★★ ★★★★★ ★★★★ ★★★

Example Files

  • valid/basic.toml — 2 rows × 2 columns, inline cells
  • valid/no_title.toml — title omitted
  • valid/empty_cells.toml — no cells defined (sparse table)
  • valid/basic.json — JSON format
  • invalid/no_rows.toml — missing rows → error
  • invalid/no_columns.toml — missing columns → error
  • invalid/invalid_cell_ref.toml — row uses undeclared column key → error
  • invalid/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.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
columns[].label2 columns, 2 rows21 / 2140 / 40
rows[].label2 columns, 2 rows12 / 1223 / 23
rows[].<column>2 columns, 2 rows21 / 2140 / 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

FieldTypeRequiredValues / meaning
kindenumyescomparison
titlestringno

columns — 1 to 8 elements

FieldTypeRequiredValues / meaning
labelstringyes

rows — 1 to 10 elements

FieldTypeRequiredValues / meaning
labelstringyes
<column>stringnoone 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