jsontables 0.1.0

A minimal format for representing tabular data in JSON

JSON‑Tables (JSON‑T) Proposal

🧩 Overview

JSON‑Tables (aka JSON‑T) is a minimal, backward‑compatible specification for representing tabular data in JSON. It enables easy human‑readable rendering, clear table semantics for tooling, and seamless loading into analytics libraries like pandas, spreadsheet apps, and data pipelines.

"Finally, a standard for representing tables in JSON—simple to render, easy to parse, and designed for humans and tools alike."

---

📦 Installation

Using pip (recommended)

pip install jsontables

From source

git clone https://github.com/featrix/json-tables.git
cd json-tables
pip install -e .

Quick test

# Test the CLI
echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]' | jsontables

# Test the Python API
python -c "import jsontables; print('✓ Installation successful!')"

---

🔥 Before & After: Why This Matters

😩 The Problem Today

[
  {
    "name": "Alessandra",
    "age": 3,
    "score": 812
  },
  {
    "name": "Bo",
    "age": 14,
    "score": 5
  },
  {
    "name": "Christine",
    "age": 103,
    "score": 1000
  }
]

• This is how JSON is typically rendered by pretty-printers.
• It's verbose and vertically fragmented, despite clearly being a table.
• Hard to visually compare rows or spot column-level anomalies.
• Hard to skim or diff in logs.
• Requires external tooling to view as a table.

✅ JSON‑Tables Solution (auto‑render)

[
  { name: "Alessandra" , age:   3 , score:  812 },
  { name: "Bo"         , age:  14 , score:    5 },
  { name: "Christine"  , age: 103 , score: 1000 }
]

• Column‑aligned, readable, diff‑friendly.
• Shows structure without visual clutter.
• Perfect for log files, CLIs, and notebooks.
• Column‑aligned, readable, diff‑friendly.
• Perfect for log files, CLIs, and notebooks.

---

1. Motivation

If you're the kind of person who deals with structured data all day—API responses, pipeline outputs, analytics logs, git diffs, or large datasets—you already live in JSON. You use jq, you open logs in vim, you paste objects into chat windows, and you pass data between services, scripts, and notebooks.

You're someone who notices when something is off by a single space. You think in columns even when you're reading trees. You want to see your data—not decode it.

And yet: default JSON pretty-printers explode tabular data vertically. Tables become forests. Alignment disappears. Visual structure vanishes.

Let's put it this way:

If you're:

• Skimming logs or scanning API outputs,
• Wrangling data frames or debugging pipelines,
• Building devtools or inspecting traces in jq,
• Sharing samples with teammates or dropping JSON into ChatGPT...

You're already reading tables. You just don't get to see them as tables.

JSON-Tables fixes that.

Instead of pretty-printed forests of curly braces, you get aligned, readable, diffable rows. You stop wasting vertical space and cognitive energy. You stop re-parsing column structures in your head. You stop reimplementing the same table renderers or naming hacks.

You just say one thing: "__dict_type": "table".

To be blunt: if you regularly work with tabular JSON and this doesn't seem useful to you—that's weird.

We built the modern data world on JSON, and yet there's never been a common way to say "this is a table." This proposal fixes that.

---

2. Human‑Friendly Rendering: ASCII Table Style

A renderer SHOULD align flat row objects if:

• Rows share identical keys.
• Values are primitives (string, number, boolean, null).
• Total rendered width ≤ 300 characters (configurable).

Example shown above.

---

3. Canonical Table Object (row‑oriented)

{
  "__dict_type": "table",
  "cols":     ["name", "age", "score"],
  "row_data": [["Mary", 8, 92], ["John", 9, 88]],
  "current_page": 0,
  "total_pages": 1,
  "page_rows": 2
}

Required Fields

Field	Type	Description
__dict_type	"table"	Signals table object
cols	string[]	Ordered column names
row_data	any[][]	Row‑major values

Optional

current_page, total_pages, page_rows allow paging.

---

4. Columnar Variant

{
  "__dict_type": "table",
  "cols": ["name","age","score"],
  "column_data": {
    "name":  ["Mary","John"],
    "age":   [8,9],
    "score": [92,88]
  },
  "row_data": null
}

Compatible with columnar storage systems (e.g., Apache Arrow).

---

5. Reference Implementation

A full, MIT‑licensed reference implementation (including CLI) lives in jsontables.py on GitHub:

👉 featrix/json‑tables/jsontables.py

The same repository contains unit tests, documentation, and a VS Code preview extension prototype.

---

6. Example Rendering

Here's an example of what jsontables can do in the wild:

📄 example.json:

[
  {"name": "Alessandra", "age": 3, "score": 812},
  {"name": "Bo", "age": 14, "score": 5},
  {"name": "Christine", "age": 103, "score": 1000}
]

💻 Terminal:

$ cat example.json | jsontables
[
  { name: "Alessandra" , age:   3 , score:  812 },
  { name: "Bo"         , age:  14 , score:    5 },
  { name: "Christine"  , age: 103 , score: 1000 }
]

Clean, readable, and aligned — just like a table should be.

---

7. Development Quick‑Start

# Clone & install in development mode
$ git clone https://github.com/featrix/json-tables.git
$ cd json-tables
$ make install-dev

# Development commands
$ make help                            # show all available commands
$ make test                            # run tests
$ make demo                            # quick demo
$ make build                           # build distribution packages
$ make clean                           # clean up build artifacts

# CLI usage examples
$ cat data.json | jsontables           # autodetect & render
$ jsontables --max-width 120 file.json # narrow terminals
$ jsontables --to-json-table file.json # convert to JSON-T format

---

7. Future Extensions (Roadmap)

• col_types, col_nullable, col_meta, dataset‑level meta.
• Binary/Arrow encoding.
• VS Code / Jupyter syntax‑aware renderers.
• Streaming & chunked table support.

---

8. Real‑World Use Cases

• Web APIs returning paged tables with schema.
• AI agents auto‑charting JSON‑T responses.
• Logger/CLI debug dumps.
• Pandas: df.to_json(table_format="json-t").
• Low‑code & spreadsheet import/export.

---

9. Status

Open proposal — feedback, issues, and PRs welcome!

---

🙋 FAQ / Objections

Why not just use CSV?
CSV is great for simple flat data, but JSON supports nesting, typing, nulls, and inline metadata. JSON-T fits the rest of the JSON ecosystem.

Why not just render my list of dicts?
Sure—but how does a tool know it's a table? __dict_type: "table" makes the intent explicit and unlocks paging, schema, column ordering, and more.

Why not just use a JSON Schema?
JSON Schema is too heavyweight and verbose for inline use. JSON-T is designed for lightweight, idiomatic scenarios.

Why not just use Arrow or Parquet?
Those are great—but they're binary formats. JSON-T works anywhere JSON works (logs, APIs, GitHub diffs, chatbots, etc).

---

🏢 Adoption

Used by:

• Featrix.ai
• runAlphaLoop.com
• Data Culpa

---

💬 Quote

"Finally I can look at a JSON table without cursing."
— You, probably

Name: JSON‑T / JSON‑Tables
Author: Mitch Haile, Featrix.ai
License: MIT License

---

🔗 Related Work

• W3C "CSV on the Web" / JSON Table Schema
• Apache Arrow JSON Format
• Google Visualization API Table Format
• JSON-stat
• OpenRefine Export Format
• CKAN JSON Table Schema usage