PORTABILITY
Choose a CSV or JSON handoff
Preserve identifiers, repeated headings and empty values by deciding what the receiving tool should understand before choosing an export.
The receiving application is part of the file format decision. A person inspecting a table and a program loading records may need the same values packaged differently. Start with the operation they must perform, then choose the representation.
This guide follows the same fictional inventory through two exports from CSV Table Lab. The CSV option retains the table’s record order. The JSON option uses a columns array beside an array of rows. Neither option decides what an item identifier, quantity or blank value means for the recipient.
Declare the meaning of a column before changing its type
An identifier such as 0017 looks numeric but acts as a label in our example. Converting it to the number 17 removes a visible part of that label. Similarly, the string 03/04 has no declared date format. A portability check should preserve those strings until an explicit column contract says otherwise.
For the sample handoff, write: item_id is text, quantity is a whole-number count when supplied, and an empty quantity means not recorded. These are fictional project decisions, not assumptions built into CSV. The worksheet gives the sender and recipient a place to agree on them before any conversion.
Use positional JSON when headings are not reliable keys
JSON objects use named members; RFC 8259 recommends unique names because duplicate names lead to inconsistent interpretation. Turning two CSV columns both named note into one object can therefore lose a distinction. Empty headings create another naming question.
The lab avoids that conversion. Its JSON has a columns array and a rows array of arrays. Headings can repeat without overwriting values, and the position of each cell still links it to its heading. When the heading option is off, columns is null and every input record appears in rows. This is the lab’s documented structure, not a universal JSON table standard.
| Input cell or heading | CSV parsing | JSON export |
|---|---|---|
| 0017 | Text unchanged | "0017" |
| 0 | Text unchanged | "0" |
| Empty cell | Empty string | "" |
| Two note headings | Both positions retained | Both names retained in columns |
| Heading option off | All records remain | columns is null; all records in rows |
Write down the small JSON contract
The handoff contract is short: columns is either an ordered list of heading strings or null; rows is an ordered list of equally wide arrays; every cell is a string. A receiver can validate that shape before transforming any quantity or date. Keep the contract beside the file so a later user does not mistake strings for inferred types.
RFC 8259 specifies JSON’s value types and ordered arrays. It also requires UTF-8 for exchange between systems outside a closed ecosystem. The lab writes UTF-8 JSON with escaped string content through the browser’s standard JSON serializer. It does not add a byte order mark to the JSON export.
Choose an export by its destination
For a program that accepts the columns-and-rows contract, JSON is an explicit way to preserve strings. For a tabular import workflow, CSV may be the better fit, but choose the destination’s import settings deliberately. The lab’s default CSV mode labels formula-like cells with the visible prefix text: ; its raw CSV option preserves values and downloads as a text file.
The filename is a cue, not a security boundary. Renaming a raw CSV text file or opening it through a spreadsheet may cause values to be interpreted. Keep a pristine raw copy for inspection, and make any human-viewing copy separately. The guide on formula-like text explains why a visually harmless preview is not enough.
Compare the reconstructed table, not the file length
A JSON file may be larger because punctuation and indentation make its structure visible. A normalized CSV may contain more quotes than its input. Neither size difference establishes data loss. Reconstruct the rows from the export and compare the exact strings, including line breaks and leading spaces.
Use three checks before calling the handoff complete: the record count matches, the heading decision is recorded, and a selected set of troublesome values survives. Then ask the receiving application to perform its real operation on the fictional sample. Record the application/version and import choices; a parser-only check does not prove that later step.
Reproduce a handoff with two note columns
This small fixture is fictional. In CSV Table Lab, replace the sample with the heading record item_id,note,note. On the next line enter 0017,"Shelf A, blue",. For the final record, start 0018,"First line, insert a real line break inside the quoted field, then finish with Second line",03/04. Choose Inspect CSV and leave the heading option on. There are two data records and three columns, even though the source occupies four physical lines.
The repeated headings are intentional: they represent separate positions whose meaning the handoff still needs to explain. Inspect the JSON export. Its columns array keeps both occurrences of note; the empty third cell in the first data record remains an empty string. The identifier 0017 and the date-like text 03/04 remain strings. Turning headings off moves the heading record into rows and changes columns to null; it does not discard that record.
Now make one controlled mistake: remove the trailing comma from 0017,"Shelf A, blue", and inspect again. The lab reports that record 2 has two fields where three were expected. Restore the comma before continuing. An empty field and an absent field require different actions.
A September 12 check executed the parser and export functions directly with this fixture. Re-parsing the raw CSV export preserved every cell exactly. That observation covers this fixture and these functions; browser downloads and spreadsheet imports were not tested. Use the handoff worksheet to record the destination check separately.
Continue with CSV Table Lab, then CSV and JSON handoff worksheet.
| Check | Observed result |
|---|---|
| Heading option on | 2 data records; columns = ["item_id","note","note"] |
| First data record | ["0017","Shelf A, blue",""] |
| Multiline note | One cell contains First line, a line break, then Second line |
| Heading option off | columns = null; 3 rows including the original headings |
| Raw CSV export and re-parse | All parsed cell values equal the original values |
| Remove first data record’s final comma | ROW_WIDTH: Record 2 has 2 fields; expected 3 |