Skip to content

docs: add PRIOR-ART.md — prior formats compared, gaps with proposed solutions#30

Open
LeslieOA wants to merge 3 commits into
developfrom
docs/prior-art
Open

docs: add PRIOR-ART.md — prior formats compared, gaps with proposed solutions#30
LeslieOA wants to merge 3 commits into
developfrom
docs/prior-art

Conversation

@LeslieOA

@LeslieOA LeslieOA commented May 26, 2026

Copy link
Copy Markdown
Member

Comparison file living in `docs/` alongside SPEC, ARCHITECTURE, DECISIONS, PERMISSIONS. Naming matches the convention (single-noun, factual).

What's in it

  1. The thesis — `.table/` is a portable database that doubles as a spreadsheet; data integrity + portability ranked above presentation.
  2. Formats compared: CSV, Excel SpreadsheetML, Frictionless Tabular Data Package, Airtable JSON, Notion DB export.
  3. Cross-cutting comparison table — 13 axes (container, types, schema, identity, relations, views, long-form content, attachments, formulas, styling, diff-friendliness, spec size, ecosystem).
  4. Closest analogue is Frictionless TDP — same shape (directory of schema + data), different audience (publishing vs. application).
  5. Gaps with proposed solutions — for each thing other formats have that `.table/` doesn't:
    • Computed / formula fields → `computed: { expr, dialect }` in schema
    • Multi-target relations → `cardinality: "one" | "many"` flag (defaults preserve current behaviour)
    • Cell-level rich text → markdown via existing `format: "markdown"` declaration; complex content stays in bodies
    • Revision history → `history.ndjson` extension (parked issue Future: history.ndjson extension (deferred) #10)
    • Cell styling → intentionally not modelled (presentation concern)
    • Multiple tables per container → already solved by sibling `.table/` dirs + relation grammar
    • Range references in formulas → not a gap; positional refs break under reordering, id+filter is the better primitive
    • Ecosystem → CSV converter (CSV converter (fromCSV / toCSV) #5) + portable Rust core (Portable reference core in Rust (single canonical parser/writer/validator) #19) + a minimum-viable-reader doc section

What this PR isn't

Test plan

🤖 Generated with Claude Code

LeslieOA added 3 commits May 26, 2026 16:38
@LeslieOA
docs: add PRIOR-ART.md — comparison vs CSV / Excel / Frictionless / A…
1e9a6fe 
…irtable / Notion

How \`.table/\` sits relative to existing formats, with a focus on
where it deliberately doesn't compete (presentation, formulas,
styling) and where it has real gaps that should be closed (computed
fields, multi-target relations, ecosystem).

Each gap has a concrete proposed solution sketched out — minimum
viable, backwards-compatible, and tied to existing issues where
relevant (computed fields ↔ a future spec extension; multi-target
relations ↔ a \`cardinality\` field; ecosystem ↔ #5 CSV converter +
#19 Rust reference core).

Naming matches the existing docs/ convention (SPEC, ARCHITECTURE,
DECISIONS, PERMISSIONS) — single-noun, factual.
@LeslieOA
docs: split styling section into decoration vs schema-encoded semantics
9364a66 
Original section dismissed cell styling wholesale. That conflated two
different things:

- Excel-style per-cell decoration (conditional formatting rules,
  manual highlighting, custom fonts / borders) → stays out. It's
  presentation, doesn't round-trip, used as private annotation.

- Notion / Airtable-style schema-encoded display semantics (per-enum-
  value colors, number/date format strings, field descriptions and
  icons) → in scope, and the right place to invest. Author intent
  travels with the data; two consumers agree on "active = green"
  because the schema says so.

Concrete proposed schema additions sketched out:
- Per-enum-value display objects (value, color, label) with backwards-
  compatible coercion from current string-array form
- Number \`format\` strings (closed set: integer, decimal:N, percent,
  currency:CODE, duration:UNIT)
- Date \`format\` strings (iso, short, long, relative, weekday)
- String \`format\` extensions (plain, markdown, url, email, phone)
- Field \`description\` and \`icon\`

Color values stay symbolic (\`green\`, not \`#22c55e\`) so consumers
own the palette. Format vocabularies are closed, not arbitrary printf.

Thesis section at top updated to reflect the cleaner position —
"author intent that round-trips" replaces the vaguer "presentation is
the consuming app's job."
@LeslieOA
docs: clarify — no private layer; cell decoration discouraged structu…
bce0d3b 
…rally

Previous revision framed "Excel-style cell decoration" as a private
annotation system. That conflated two unrelated things and got the
positioning wrong.

\`.table/\` has no private layer. Everything written into the directory
is visible to every authorized consumer, identically. The right reason
to exclude per-cell decoration isn't that it'd be private — it's that
the format pushes authors toward "make it a field" (typed, named,
queryable) over "scribble a color on it" (none of those).

Updates:
- Thesis: spells out "no private layer" explicitly.
- Cell-level-decoration section: reframed around the structural-vs-
  scattered argument, not the private-vs-shared one.
- New "What lives OUTSIDE a \`.table/\`" section enumerates the
  consumer-local concerns the format intentionally doesn't carry —
  per-user UI prefs, selection state, ACLs, computed view results.
  Anchor for future questions about user-local styling.
This was referenced May 26, 2026
Open
Open
Open
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@LeslieOA