Data files
A .csv, .json or .jsonl artifact is data the reader takes somewhere else: a spreadsheet, a script, an import, another system. "Export the open incidents", "give me every contract as a CSV" and "the raw results as JSON" ask for one.
The pane shows only part of a data file. A table the reader needs to read belongs in a Markdown document. When the export is the point and the reader also needs the explanation, an assistant publishes both: the .md that explains it and the data file that carries every row.
| Extension | The pane shows | The download has |
|---|---|---|
.csv |
The first 200 rows as a table, with the first row as the header. A notice under the table says the rest is in the download when there are more. | The whole file. |
.json |
A tree with the top level open. Each object and array shows its first 100 entries and a count of the rest. Strings longer than 200 characters are cut and shown whole on a click. | The whole file. |
.jsonl |
The first 200 records. A table with a column per key when every record is a flat object, a tree of records otherwise. | The whole file. |
CSV
The first row is the header and a comma separates the fields. A field that holds a comma, a quote or a line break is quoted, with its quotes doubled: "Smith, J." and "6"" pipe". publish does not reject a CSV for its shape, because any text is a table of some shape. Writing the quoting by hand goes wrong, so an assistant writes the file with a tool that does it, such as Python's csv module or jq -r '... | @csv'.
python3 - <<'EOF'
import csv
rows = [("Ticket", "Status"), ("T-9182", "open"), ("T-9190", "closed")]
with open("/artifacts/q3-incidents.csv", "w", newline="") as f:
csv.writer(f).writerows(rows)
EOF
publish q3-incidents.csv
JSON and JSON Lines
.json holds one JSON document. .jsonl holds one complete JSON value per line, and nothing spans two lines. jq -c '.[]' turns a JSON array into JSON Lines.
publish parses both before it accepts them. A .json file that does not parse is refused, and so is a .jsonl file with a bad line. The message gives the line and the reason, so the assistant can fix the file and publish again.
Naming
A data file has no title of its own and appears under its file name, so the name is what the reader sees. q3-incidents.csv is a useful name and data.csv is not.
Limits
One artifact holds at most 1,000,000 characters of source. For a larger export, the assistant publishes the part the reader asked about and says what was left out.