JSON Lines

Examples


Better than CSV

["Name", "Session", "Score", "Completed"]
["Gilbert", "2013", 24, true]
["Alexa", "2013", 29, true]
["May", "2012B", 14, false]
["Deloise", "2012A", 19, true] 

CSV seems so easy that many programmers have written code to generate it themselves, and almost every implementation is different. Handling broken CSV files is a common and frustrating task. CSV has no standard encoding, no standard column separator and multiple character escaping standards. String is the only type supported for cell values, so some programs attempt to guess the correct types.

JSON Lines handles tabular data cleanly and without ambiguity. Cells may use the standard JSON types.

The biggest missing piece is an import/export filter for popular spreadsheet programs so that non-programmers can use this format.

Self-describing data

{"name": "Gilbert", "session": "2013", "score": 24, "completed": true}
{"name": "Alexa", "session": "2013", "score": 29, "completed": true}
{"name": "May", "session": "2012B", "score": 14, "completed": false}
{"name": "Deloise", "session": "2012A", "score": 19, "completed": true} 

JSON Lines enables applications to read objects line-by-line, with each line fully describing a JSON object. The example above contains the same data as the tabular example above, but allows applications to split files on newline boundaries for parallel loading, and eliminates any ambiguity if fields are omitted or re-ordered.

Easy Nested Data

{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]}
{"name": "Alexa", "wins": [["two pair", "4♠"], ["two pair", "9♠"]]}
{"name": "May", "wins": []}
{"name": "Deloise", "wins": [["three of a kind", "5♣"]]}

JSON Lines' biggest strength is in handling lots of similar nested data structures. One .jsonl file is easier to work with than a directory full of XML files.

If you have large nested structures then reading the JSON Lines text directly isn't recommended. Use the "jq" tool to make viewing large structures easier:

grep pair winning_hands.jsonl | jq .
{
  "name": "Gilbert", 
  "wins": [
    [
      "straight", 
      "7♣"
    ], 
    [
      "one pair", 
      "10♥"
    ]
  ]
}
{
  "name": "Alexa", 
  "wins": [
    [
      "two pair", 
      "4♠"
    ], 
    [
      "two pair", 
      "9♠"
    ]
  ]
}