JCSV file format Version 1.1

JCSV (JSON Comma Separated Value) is a line-delimited JSON file format designed to combine the simplicity of CSV with the structured data capabilities of JSON. It makes data easier to describe, interpret, validate, and process by supporting both tabular data and metadata within the same file.

Unlike traditional CSV, JCSV can include multiple tables or structured data sections in a single document, making it suitable for software interoperability, AI-assisted data analysis, and long-term data archival.

Version 1.1 is an evolution of JCSV 1.0. It is still under development and introduces features intended to make the format more AI-friendly, self-descriptive, and reliable for preserving reusable data over time.

JCSV principles

The JCSV file is composed of rows, similar to a CSV file, but with two specific types of rows:

• Metadata rows, within {} brackets, in the form of a valid JSON object in compact form, followed by a new line. In the example, this is the "column-names".
• Data rows, within [] brackets, JSON arrays, followed by a new line. This is the CSV data, formatted as a valid JSON array. The data contains the values in the same sequence as the column headers.

Other rows, not within [] or {} brackets, are ignored.

This is the JCSV equivalent of a CSV file. All rows are valid JSON elements, so parsing does not depend on external parameters.

{"columnNames":["Account","Description","Opening","Balance"]}
["1000","Cash on hand",100,1290.3]
["1020","Bank account",0,10]
["2000","Suppliers",-50,-10]

The CSV equivalent

Account,Description,Opening,Balance
1000,Cash on hand,100,1290.3
1020,Bank account,0,10
2000,Suppliers,-50,-10

Why JCSV is AI-friendly

ICSV is more self-descriptive than CSV, simpler than XML, more readable than binary formats, and better suited to complex tabular data than a single large nested JSON file.

• Unambiguous parsing: unlike CSV, JCSV does not depend on field separators, quoting rules, empty lines, or locale-specific conventions.
• Explicit column order: columnsNames clearly maps array values to column names.
• Multiple tables in one file: related data can stay together instead of being split across many CSV files.
• Rich metadata support: columns can describe types, formats, constraints, decimals, and descriptions.
• Semantic layer: semantics can explain roles, relationships, keys, references, units, and meanings.
• Less ambiguity: AI does not need to guess what columns or codes represent.
• Lower computational overhead: explicit structure and semantics can reduce inference, clarification, and error-correction work during AI-assisted analysis.
• Line-oriented structure: each line is either metadata {} or data [], making parsing simple and predictable.
• Plain text format: easy for AI systems to read, inspect, and reason about.
• Stream-friendly: files can be processed sequentially, even when large.
• Human-readable: both humans and AI can understand the file without specialized binary tools.
• Good balance: combines the simplicity of CSV with the context usually missing from CSV.

Why JCSV is suitable for long-term data preservation

• Plain text format: data remains readable without depending on a specific application or binary format.
• Based on JSON syntax: uses a widely known, stable, and well-supported data representation.
• Unambiguous parsing: avoids common CSV issues such as separators, quoting rules, empty lines, and locale-dependent formatting.
• Self-describing structure: metadata, table names, columnsNames, and optional columns help future users understand the file.
• Multiple tables in one file: related datasets can be preserved together, reducing the risk of losing context between separate files.
• Reusable by data-management applications: tables, column names, metadata, and relationships can be imported or mapped into databases, spreadsheets, ETL tools, and analysis software.
• Semantic information: semantics can document roles, relationships, references, units, and meanings that might otherwise be lost.
• Human-readable: future users can inspect the file with a simple text editor.
• Software-independent: the file can be interpreted without the original program that created it.
• Versionable: the jcsv metadata can include a format version, helping future parsers apply the correct rules.
• Stable for archival workflows: the line-oriented structure is easy to validate, diff, store, compress, and checksum.
• Good balance: combines the longevity of plain text with more structure and context than traditional CSV.

JCSV format specification

See example below.

• UTF8 character encoding.
  The UTF8 encoding is mandatory. 
• Line-delimited JSON format in which each physical line contains one complete JSON value.
  • Line endings must use LF, Line Feed, U+000A ("\n"). 
    Readers should also support CRLF, U+000D U+000A ("\r\n"), for compatibility, but a standalone CR, U+000D ("\r"), must not be considered a valid line break.
  • Writers should always emit LF line endings and omit CR characters.
  • LF must be used only to terminate physical lines and must not occur unescaped inside a data or metadata line. If a text value requires an internal line break, it should use LS, Line Separator, U+2028, or another appropriate application-defined replacement or escaping convention.
• Metadata lines
  • Meta data line start "{" and end with the  "}" brackets.
  • They need to be valid JSON Objects (JSON document), in compact format (No space and no end of line).
  • Metadata lines comes before the data.
    • {"table": {"name": "Accounts"}  data that follows will be considered belonging to the "Accounts" table.
    • Other metadata like row styles {"rowStyle":{"bold":true,"fontSize":10}} come before the data row.
  • Reserved metadata keyword:
    • "jcsv" with version and encoding.
      If the file name has the extension "jcsv" the element is not necessary. 
    • "generator" contains information regarding the application that has generated the file.
    • "document" contains information regarding the file.
      • Add any element that may be helpful to understand the data, like name, header, description, etc.
      • All successive elements before the next "document" should be belonging to this document.
    • "semantics" is a table element containing information that help interpret the content.
    • "comment" for entering comments
    • "table" contain the name of a table.
      • Add any element that may be helpful to understand the data, like name, header, description, etc.
      • All rows following the "table" are considered to belong to this table.
    • "columnNames" is a mandatory element that contains a JSON Array with the columns names.
      The data rows following the columns are considered to be in the sequence of the columns name.
      A "column-names" that does not follow a "table" is considered to start a new table.
    • "columns" contains information relative to the columns.
      The columns information is not necessarily in the sequence of the data, so the  "columnsNames" should always be present.
    • "rowStyle" contain supplementary information regarding the following data row.
• Data lines.
  Are the lines that contain the real data (CSV data) 
  • They should be preceded by the {"table"}.
  • The line element is a JSON Array that starts with the "[" and terminate with the "]" .
  • The number of element within the array must be the same size as the preceding column-names.
  • Data is stored in JSON format.
    • String are between ".
      • Usual string "Bank account".
    • Date, Time and Timestamp are JSON string in the ISO date format 8601
      • Date  "2018-01-03".
      • Time "10:18:21.000".
      • Timestamp "2016-11-19T09:52:39".
    • Number in valid JSON format, decimal separator "."
    • true or false.
    • null.

• Other lines not being a valid JSON Object or array (like empty lines, text or else) are not considered.

   

JCSV document examples

/* text that is not within {} or [] is ignored */
{"jcsv" : {"version" : "1.1", "encoding":"UTF-8"}}
{"document":{"Application":"Banana","Application version":"8.0.4.160915"}}
{"table":"Accounts"}
{"column-names":["Section","Group","Account","Description","Boolean","BClass","Gr","Opening","Balance"]}["","","1020","Bank account",false,"1","10",0,10]
["","","2000","Suppliers or Creditors",false,"2","20",-50,-50]
["","28","","Equity",false,"","2",-250,-1450.3]

{"table":"Transactions"}
{"column-names":["Date","Time","Doc","Description","AccountDebit","AccountCredit","Amount"]}
["2018-01-03","10:18:21.000","1","Cash to Bank","1020","1000",10]
["2018-02-02","23:55:00.000","2","Sales","1000","3400",1200.3]

In the following example it is used the "columns" specification with metadata information regarding each column.

{"table":"Accounts"}
{"column-names":["Account","Balance"]}
{"columns":[{"name":"Account", "datatype":"string","titles":"Account"},{"name":"Balance","titles":"Balance", "datatype":{"base":"number","scale":1}}]}
["1020",10]
["2000",-50]

JCSV files

• Mime type "text/jcsv".
• File extension ".jcsv".
• Encoding "UTF-8".

Try the JCSV format

You can try a new format by installing the Banana Accounting software.

• See JCSV example files on Github\BananaAccounting
• Open or drag a JCSV file in Banana
  Banana will create a new file tables and columns. You can the copy and paste the data in Excel.
• Export in JCSV 
  • Export of a single table
    Menu Data -> Export Rows->JCSV 
  • Export of all the tables
    Menu File -> Export ->JCSV

Using JSON library to generate or read the JCSV format

Generating JCSV files

1. Create a JSON Object that contains and JSON Array with the columns name and convert to JSON text, plus the line feed.
2. For each data row create a JSON array that contains the data and convert to JSON text, plus the line feed.

Parse JCSV files

1. Read each line.
2. If lines start with "{" and end with "}" parse as JSON and extract the values.
3. If lines start with "[" and end with "]" parse as JSON and get the data.

Javascript example for generating and parsing JCSV 

// Create and parse JCSV data in Javascript
// header
var text = JSON.stringify({"column-names" : ["Date", "Name", "Amount"]}) + "\n";
// Data row
text += JSON.stringify(["2018-01-24", "John Smith", 1200.10]) + "\n";
text += JSON.stringify(["2018-12-31", "Maria Callas", -200]) + "\n";

// parse JCSV data
var lines = text.split("\n");
for (i = 0; i < lines.length; i++)
{
  // header lines
  if (lines[i].startsWith("{") && lines[i].endsWith("}"))
  {
    JSON.parse(lines[i]);
  }
  // data lines
  if (lines[i].startsWith("[") && lines[i].endsWith("]"))
  {
    JSON.parse(lines[i]);
  }
}

Creating and parsing the JCSV file without the JSON library

Generating the file

• Write the header line as a simple text with the header.

"{"column-names" : ["Date", "Name", "Amount"]}\n"

• Create a CSV with the data that follow the rules of JSON data.
  Add at the begin the "[" and at the end the "]".

Parse the JCSV file

• Read the file line by line.
• Process the lines that start with "{" and end with "}".
• Process as data the lines that start with "[" and end with "]" as a normal CSV data structure.

Author

The JCSV specification has been conceived and developed by Domenico Zucchetti, founder and CEO of Banana.ch and creator of Banana Accounting.

Domenico Zucchetti has more then 30 year of experience in international accounting and as legal expert and software developers. He has been a blockchain pioneer. In 2002, it was the first in the world to implement a blockchain certification functionality in an accounting software.

D. Zucchetti welcomes feedback.

Updated documentation

• At the beginning of 2026, some users signaled that the format was interesting for use with AI tools. In May 2026, we made the format more AI-friendly. We updated the column format and added the "file" and "generator" elements. The documentation has also been updated accordingly.