Skip to content
kindspecPublic

About

A specification and conformance suite for tabular data that must survive version control

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rowspec

A file format and test suite for tables that must survive version control.

A .mdtbl file is a markdown table where a computed column carries its formula in the header, rows have opaque ids, and nothing is addressed by position. The point is that stock git merges it correctly, or refuses — never quietly wrong, with none of this project's tooling installed.

| id     | item   | qty | unit  | total = qty * unit |
| ------ | ------ | --: | ----: | -----------------: |
| r_0001 | widget |  10 | 12.00 |                    |

key   := id
grand := sum(total)

Two branches insert a row far apart. Stock git merge — no driver, no .gitattributes, nothing installed — merges cleanly, and grand is correct. The same table with A1-style references merges just as cleanly and reports a number that is 27% wrong, with no marker anywhere. That difference is the entire project.

Quick start

pip install rowspec
rowspec check .    # will this table survive being edited by several people?
rowspec eval  .    # does it currently say anything false?

Run both. check finds structural problems, and eval computes every table and fails on an unresolved value. A misspelled column name passes check and leaves a wrong total, so check alone is not enough.

Already have CSV files? rowspec check data/ works on them with no migration. See CSV mode.

In CI

- uses: actions/checkout@v7
- uses: kindspec/rowspec@v0.7.0
  with:
    paths: data

The action runs both commands.

Edit a table

rowspec add-row parts.mdtbl bolt 4 0.10
rowspec rename-column parts.mdtbl qty quantity
rowspec add-column parts.mdtbl note --after item

Each edit changes only the lines it is about, so edits on two branches merge wherever they don't touch neighbouring lines. Programs can call rowspec.edit; see the editing API.

Do you need it?

If your table is a list of facts, you probably do not need this. Across 7,446 real commits from four public CSV-in-git registries, including 528 real three-way merges, neither .mdtbl nor plain CSV ever merged silently wrong.

It earns its keep when a table computes, and a merge can leave a total that is quietly wrong. It doesn't help when two branches each add a column, which conflicts as badly as it does in CSV. It isn't a data-quality tool either; for that, use Frictionless.

How it is tested

The test suite is the main deliverable. It checks out two branches, runs stock git merge, evaluates the merged file and asserts on the computed number. A second implementation, written from SPEC.md alone, runs against the same cases, and a mutation gate breaks the code on purpose to prove the suite notices.

703 conformance cases          two implementations, both passing
122 mutants, all distinct      119 killed, 3 equivalent
                                 0 survived, 0 stale, 0 broken

Documentation

SPEC.md the format
Using rowspec CSV files, CI, editing and the two commands in full
Export to xlsx pip install 'rowspec[xlsx]', formulas or values
What has been measured what it does not do, and how the suite is built
Rationale why the format is this way

Develop

A real git binary is required, because the suite's central claim is about what stock git does.

just setup      # uv sync
just check      # fmt-check + lint
just test       # everything under tests/
just conform    # the suite alone, against a stock git binary
just mutants    # break the implementation; the suite must notice

See CONTRIBUTING and just --list.

Licensing

Per directory, deliberately. See LICENSE. The fixtures are CC0 so they can be vendored into an implementation in any language under any licence.

Credit

Standing on Coopy/daff, ClassSheets, Object Spreadsheets, Lotus Improv and org-mode. See NOTICE.

About

A specification and conformance suite for tabular data that must survive version control

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages