Formats

Default

Plain — one file

Header, # lines, then ordinary CSV rows, all in sales.excsv (or sales.extsv if the delimiter is a tab). This is the canonical form: what you export, version, paste into a chat, or drop next to a notebook.

Every CSV reader that ignores # comments already reads the data. pandas: pd.read_csv("sales.excsv", skiprows=n), where n is the number of # lines. grep / awk / cut work on the rows as usual.

#!excsv version=0.6 delim=comma header=1 rows=2
#@grain: one row per order
#column name=id type=int role=id
#column name=customer type=string
#column name=amount type=decimal unit=USD role=measure
#%sum: ,,750.50
id,customer,amount
1,Acme Corp,500.00
2,Globex Inc,250.50

If the CSV already exists and you can't rewrite it — that's sidecar.

Legacy-friendly

Sidecar — annotate without touching the CSV

sales.csv stays a normal CSV — same bytes, same checksum, still opens in Excel. Next to it, sales.excsv holds only metadata and points at the data with reference=sales.csv. No rows in the sidecar. Tabs use sales.extsv + sales.tsv.

You open whichever you have. Opening the CSV, an ExCSV-aware tool looks for the sibling. Opening the sidecar, it follows reference=. Everyone else just reads the CSV.

#!excsv version=0.6 delim=comma header=1 rows=2 reference=sales.csv
#@source: sales_db.orders
#column name=id type=int
#column name=customer type=string
#column name=amount type=decimal unit=USD
#%sum: ,,750.50

id,customer,amount
1,Acme Corp,500.00
2,Globex Inc,250.50

If you control the export, a plain .excsv is enough.

Distribution

ZIP — compress, still peekable

Wrap a plain file as sales.excsv.zip (or .extsv.zip). Inside: the same inline ExCSV. Outside: a normal ZIP that anything can open. pandas will take it with pd.read_csv("sales.excsv.zip", skiprows=n).

The trick is the ZIP comment. It repeats the header, columns, and #% aggregations, so you can see schema and totals without extracting — useful when a folder is full of 200 MB exports and you need to know which one is Q1 sales.

sales.excsv.zip
└── sales.excsv          ← ordinary plain file (header + rows)

Stay on plain if you want zcat | awk without an archive. Several tables is pack. A sidecar stays two files on disk — ZIP is for one plain file.

Columnar · multi-table

Pack — columns and several tables

A .excsv.pack.zip is a small warehouse dump. Instead of storing rows, it stores each column as its own file, and can hold several tables plus the foreign keys between them. Same ExCSV metadata — types, stats, SQL — per table.

Think: you exported orders, customers, and products, and you usually only need amount and date out of a 200-column fact table. A row ZIP makes you decompress everything. A pack lets you open one .col.

sales.excsv.pack.zip
├── _manifest.excsv          ← tables + foreign keys
├── orders/
│   ├── _header.excsv        ← schema + stats for this table
│   ├── 00-id.col
│   ├── 01-customer_id.col
│   └── 02-amount.col
├── customers/
│   └── ...
└── products/
    └── ...

Wide fact tables can split each column into row chunks (default 10k) so a single cell is a short scan, not a full-column read. Small lookup tables stay as one file per column.

Stay on plain or ZIP if you want to stream rows. Pack is in v0.6; the Go CLI doesn't open it yet.

JSON-native

JSON — the same document, without the CSV

sales.excsv.json is not an export or a summary — it's the same ExCSV document with the # stripped off. Every meta line becomes a key: the header is csv, #@ is meta, #column is columns, #% is aggregates, #$ is sql.

Use it where JSON is already the envelope: a REST payload, a config file, a TypeScript frontend — or an LLM that you'd rather constrain to a JSON Schema than trust to hand-write a #!excsv header. Serve it as application/excsv+json.

{
  "excsv": "0.6",
  "csv": { "delim": "comma", "header": true },
  "meta": { "grain": "one row per order" },
  "columns": [
    { "index": 0, "name": "id", "type": "int", "role": "id" },
    { "index": 1, "name": "customer", "type": "string" },
    { "index": 2, "name": "amount", "type": "decimal", "unit": "USD", "role": "measure" }
  ],
  "aggregates": { "sum": [null, null, "750.50"] },
  "rows": 2,
  "data": [
    [1, "Acme Corp", "500.00"],
    [2, "Globex Inc", "250.50"]
  ]
}

It's JSON, not CSV — no # comment trick, no awk on the rows, no ZIP-comment preview. Stay on plain when plain-CSV compatibility is the point. Try the browser converter.