JCSV file format

Documentation •
In this article

JCSV, JSON Comma Separated Value, is an experimental AI-friendly text file format designed for tabular data. It is similar to CSV, but extends its capabilities by allowing multiple tables within a single file and by using a JSON structure, making the data easier to interpret and process.

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.

{"column-names":["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

JCSV advantages 

JCSV allows to embed in the same file the data and metadata, like table and column name, description, format and attributes, in a very simple form, without requiring a schema file.

  • JCSV can store data from multiples file and multiple tables.
  • JCSV is a better format for archiving tabular data.
  • JCSV simplify the exchange of data .

The advantages of JCSV comes from the possibility to embed any metadata in JSON .

  • Encoding specification.
  • File information.
  • Table information. It is therefore possible to include more tables in the same file. 
  • Columns sequence.
  • Field information.
  • Unlimited expansion. Any metadata information, specific to the application or the data row, can be embedded.
  • It is also possible to insert any other text. All information not within {} or [] is ignored. 

JCSV references

The JCSV is based on the accepted standards.
See the reference documentation:

JCSV format specification

See example below.

  • Use the UTF8 format
    The UTF8 format is mandatory. 
  • JCSV file is composed of text lines terminated by the "\n", LF:Line Feed, U+000A.
    • The "\r\n" should be supported in reading, but the "\r" alone is not considered as line breaking.
    • When writing the \r should be omitted.
    • The LF, Line Feed character should be used only at the end of the line and not within the data or metadata line.
    • In the data or metadata line, replace the LF char with the LS:Line Separator, U+2028 or any appropriate character you prefer.
  • 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":"Accounts"}  data that follows will be considered belonging to the "Accounts" table.
      • Other metadata like row attributes {"row":{"styleNumber":1144}} 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. 
      • "schema" a url to a document that contains the information necessary to verify the document or the table.
      • "generator" contains information regarding the application that has generated the file.
      • "file" contains information regarding the file.
        All successive elements before the next "file" should be belonging to this file.
      • "table" contain the name of a table.
        All rows following the "table" are considered to belong to this table.
      • "column-names" is a required 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  "columns-names" should always be present.
      • "comment" for entering comments
      • "row-attributes" 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": "table name"}.
    • 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.

         

Examples

/* text that is not within {} or [] is ignored */
{"jcsv" : {"version" : "1.0", "encoding":"UTF-8"}}
{"comment": "Example JCSV file"}
{"schema" : "banana.ch/testfile/test"}
{"file":{"Application":"Banana","Application version":"8.0.4.160915"}}
{"table":"Accounts"}
{"column-names":["Section","Group","Account","Description","Boolean","BClass","Gr","Opening","Balance"]}{"column-hand",true,"1","10",100,1290.3]
["","","1020","Bank account",false,"1","10",0,10]
["","","2000","Suppliers or Creditors",false,"2","20",-50,-50]
{"row-attributes":{"styleNumber":1024}}
["","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".

Advantages and limitation of JCSV format

Advantages of JCSV file format over CSV

  • JCSV follows the JSON format.
    • There is just one way to write and read the data. No more doubts about encoding, fields separators, number format, decimal separator.
    • For generating and reading a JCSV it is possible to use the JSON libraries, avoiding therefore escaping error that you find typically on CSV. .
  • JCSV can contains data of different tables.
  • Supplementary information relative to the structure or the attributes of the rows does not interfere with the data.

Advantages over JSON 

  • In JCSV each line is a unique JSON document, independent from the other lines.
    • It is possible to add lines to an existing document (Append mode).
    • It is possible to parse the lines individually.

Limitation of JCSV 

  • Like CSV the JCSV format can be used only to exchange tabular data and not nested data structure (like JSON).

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.

 

help_id
TabConvertToJCsvBase
How can we help you better?

Let us know what topic we should expand or add to make this page more useful.

Send us your feedback

Share this article: Twitter | Facebook | LinkedIn | Email