Tabular-JSON is a work in progress. The details of the specification may change.

What is Tabular-JSON?

Tabular-JSON is a data format. It is a superset of JSON, adding CSV-like tables and optional quotes. It is:

Real world JSON data often consists of an array with nested objects like a list of products, a list of messages, or a list of clients. This is verbose to write in JSON because all field names are repeated for every item in the array. This common data structure can be written much more compact in a tabular way, like CSV. Adding support for tables in a superset of JSON gives the best of both worlds.

Tabular-JSON aims to be just as simple as JSON and CSV. It combines the best of JSON, CSV, and NDJSON, but without their drawbacks. It is human-readable, compact, and supports rich data structures and streaming. The aim of Tabular-JSON is to be a data format, not a configuration format.

Read “Tabular-JSON: Combining the best of JSON and CSV” to learn more about the background of Tabular-JSON.

Playground

Play around with Tabular-JSON in the interactive playground:

Try Tabular-JSON Online

Example

Here an example of Tabular-JSON data:

{
  name: rob,
  hobbies: [
    swimming,
    biking
  ],
  friends: ---
    id, name,  address.city, address.street
    2,  joe,   New York,     "1st Ave"
    3,  sarah, Washington,   "18th Street NW"
  ---,
  address: {
    city: New York,
    street: "1st Ave"
  }
}

And here a table at root level (the rows are streamable):

id, name,  address.city, address.street
2,  joe,   New York,     "1st Ave"
3,  sarah, Washington,   "18th Street NW"

Ingredients

So what are the ingredients of Tabular-JSON?

And that’s it. The complexity of the Tabular-JSON data format is equal to that of JSON plus CSV.

The grammer of Tabular-JSON can be found on the Specification page, alongside the grammer of JSON for comparison.

Features

Data types

Tabular-JSON supports the following data types:

Data typeExampleDetection
object{ name: Joe, age: 24 }Starts with {
array[7.4, 5.2, 8.1]Starts with [
table
---
id,name
1018,Joe
1078,Sarah
---
Starts with ---
booleantrueEquals true or false
nullnullEquals null
date2024-04-05T07:49:41.501ZMatches the regex pattern \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z
number-2.3e5Starts with a digit or a minus followed by a digit
stringhello world
"hello world"		Not matching any of the other data types. Can be either a quoted or unquoted string

Differences between JSON and Tabular-JSON

FeatureJSONTabular-JSON
Double quotes around keys and stringsRequiredOptional
Table structureNot supportedSupported
Data typesobject, array, string, number, boolean, nullobject, array, table, string, number, date, boolean, null

Remarks:

Differences between CSV and Tabular-JSON

FeatureCSVTabular-JSON
Table headerOptionalRequired
Nested header fieldsNot officially supportedMultiple names separated by a dot
Double quotesPreceed by an extra double quote ""Escape with a backslash \"
DelimiterComma (officially). In practice, it can sometimes be a semicolon or tabComma
White space around valuesPart of the value, not allowed when the value is enclosed in double quotesNot part of the value
Data typesNo data typesobject, array, table, string, number, date, boolean, null
Control characterNo need to escapeEscape with a backslash
Unicode charactersNot officially supported (only ASCII characters are supported officially)Supported
Escaped unicode characters like \u263ANot supportedSupported

Remarks:

Best practices

  1. You can safely use a Tabular-JSON parser to read both JSON and Tabular-JSON data. When writing data, the output will all become Tabular-JSON though, except when the parser supports disabling optional quotes and tables. Typically, you can use this feature to smoothly migrate from JSON to Tabular-JSON.
  2. Always use a CSV parser to parse CSV data. Do not use a Tabular-JSON parser to parse CSV data, even when the data looks like valid Tabular-JSON or the other way around. There are tricky edge cases around escaping (see the differences section).

Status

There are still a couple of topics of the data format that needs to be decided upon. Please feel welcome to join the discussion.

Then, the data format has to be implemented in a couple of languages (like JavaScript, Python, and Kotlin) and published so people can actually use the format.

References