TabalystPRODUCTAvailable
Tabalyst Report
The product behind the four formats: demo, outputs, batches and Python.
Tabalyst Report · JSONAvailable
A JSON file is not a table. Tabalyst finds the records.
Tabalyst Report is an open-source tool that turns a data file into an interactive HTML report and a JSON profile, on your machine. Given a JSON file with nested records or several lists, it finds the right collection: you get a report when the choice is clear, and the list of candidates when it is not.
tabalyst report orders.json
Analyzed 60 records and 17 fields in 1 dataset.
Report: orders.report.html
tabalyst report shop.json
2 collections of shop.json are equally plausible.
Nothing was analyzed.
Candidates:
$.customers[] (2 elements)
$.products[] (2 elements)
tabalyst report shop.json --collection products
Analyzed 2 records and 2 fields in 1 dataset.
Real output of tabalyst 0.6.0, paths shortened.
One clear chain · three steps
From JSON file to a view you can use.
One JSON file, possibly several lists of records. Tabalyst Inspect picks the collection to report, and Tabalyst Report writes two outputs from it.
JSON FILE
Your file
Nested objects, arrays inside records, a header of metadata. The file is read locally and never modified.
COLLECTION SELECTION
Tabalyst Inspect
Finds the arrays of records and keeps one when the choice is clear. Here, customers is the only one. Nested fields become columns named by their path.
TWO DELIVERABLES
Human + machine
An interactive report for people, a structured profile for your tools. Both come from the one collection that was selected.
With one collection, there is nothing to choose. With several and no clear winner, Tabalyst stops, lists the candidates and you pick one with --collection.
Schematic view of the example file orders.json. Counts come from its real report.
Format
Where JSON files get tricky
- 01 / NESTING
Records inside records
Nested objects and arrays become columns named by their path: address.city, tags[], orders[].total. Nothing is flattened by hand.
- 02 / COLLECTIONS
Several lists in one file
A file can hold customers and products side by side. Each array of records is a candidate; values outside the chosen one are not analyzed.
- 03 / PRESENCE
Fields that come and go
A field absent from a record counts as missing. The JSON structure section shows, for every path, how often it is present and which types it takes.
The idea
Simple. Clear. Smart.
Simple. Clear. Smart.
Simple
One command for any JSON file: tabalyst report file.json. Nothing to configure when the collection is clear.
Clear
When it cannot choose, it stops with exit code 2 before analyzing anything and lists every candidate. Tabalyst Inspect prints one ready-to-run command per collection.
Smart
Tabalyst Inspect keeps a collection only if it is the only array of records, or has at least 10 times more elements than the next. Otherwise it asks.
How Inspect chooses ↗
Outputs
What you get
Tabalyst Report writes three files beside the source: orders.report.html, an interactive report for people; orders.report.json, a structured profile for code; and executions.json, the history of successful runs.
A JSON report adds a JSON structure section: every path of the records, the types found, how often the field is present and the lengths of arrays.
Proof
See a real JSON report
A synthetic export of 60 shop customers, each with an address and nested orders. Tabalyst finds the customers collection, names the 17 fields by path and adds a structure section.
- Source
- JSON
- Records
- 60
- Fields
- 17
- Missing cells
- 48
Run it
Run it on your file
Tabalyst Report is open source and runs on your machine. It needs Python 3.11 or later.
- 1 · Install
pip install tabalyst# Also updates it: Tabalyst changes often
- 2 · One file, one collection
tabalyst report orders.json# The report and the profile are written beside the source
- 3 · Several lists: see the choices
tabalyst report shop.json# Nothing is analyzed: it lists the candidates, such as $.customers[] and $.products[]
- 4 · Pick one
tabalyst report shop.json --collection products# Or run tabalyst inspect shop.json to write the choice once in an Inspect file
import tabalyst # One file, one collectionbatch = tabalyst.generate_reports(["orders.json"], output_dir="reports") # Several lists: batch.failures lists the candidates.# Choose one in tabalyst.json: {"scan": {"json": {"collections": ["$.products[]"]}}}batch = tabalyst.generate_reports( ["shop.json"], output_dir="reports", config_path="tabalyst.json",)print(batch.succeeded)
The JSON guide ↗ and the Inspect guide ↗ cover collections, flattening and Inspect files. To report several collections of one file, pass --collection once for each.
Scope, not hype
What to know before you start
- One collection per report by default. A file that is a single object, a number or an array of plain values has no collection.
- A syntax error anywhere in a
.jsonfile stops the analysis: Tabalyst does not repair a damaged document. - Relations between collections are not analyzed.
The known limitations ↗ list the rest.
Your next JSON file
Let Tabalyst find the records.
Install Tabalyst, point it at a JSON file and open the report, or pick from the candidates.