Import JSON Files

VisiGrid reads JSON through an import recipe: a .json export from an API or a download, or a JSON Lines file (.jsonl, .ndjson) with one record on each line. Each record becomes a row of a Table, and Refresh reads the next export the same way. JSON sources start in VisiGrid 0.51.0.

Note

From 0.52.0, File → Open on a JSON export opens the recipe builder on it. In 0.51.0, File → Open reports Unknown file type: json: use Data → New Import Recipe… instead.

Try it with a sample

Download the sample export and its recipe into the same folder (or right-click a link and choose Save Link As…):

• shop-orders.json: eight orders from a fictional shop, as an e-commerce API might return them. The orders sit under an orders key, next to a page object and a smaller refunds list. Each order has a nested customer (one has no address), an id too large for a spreadsheet number, a null discount code, true/false flags and a list of items.
• shop-orders.recipe.toml: reads the orders, makes created_at a date, and keeps the paid orders.

Open shop-orders.recipe.toml with Ctrl+O. VisiGrid asks once before reading the file, then loads the Table:

• Nested objects became dotted columns: customer.name, customer.address.city. Columns come in the order they first appear in the file.
• The order with no address (LL-1044) is empty in the two address columns.
• id is text: these IDs are larger than 9,007,199,254,740,992, so as numbers their last digits would change. VisiGrid keeps the column as text with every digit.
• total is a number column, because every value in it is a JSON number.
• gift shows TRUE/FALSE, the null discount codes are empty, and each items list is kept as its JSON text in one cell.
• The two orders that aren’t paid were removed by the recipe’s filter step.

Make a recipe from your own export

1. Data → New Import Recipe…, and choose your .json, .jsonl or .ndjson file. From 0.52.0, File → Open on the file does the same.
2. The builder opens. On the left, Records at shows where the records are. VisiGrid finds them itself: the array at the top of the file, or else the largest array of records inside it. The recipe saves that path, so next month’s export reads the same records even if another array grows larger. Press Enter on Records at to choose a different array.
3. Add steps as for any recipe. Dates in JSON are text, so a Set types step (date:ymd for 2026-09-01) makes them dates. Numbers sent as strings, like "10.50", need Set types too. From 0.52.0 you can click the type under a column in the preview (Text ›) to change it: the builder adds the Set types step for you. Right-click goes back a type. Scroll the preview sideways (Shift+wheel with a mouse) to reach columns past its edge.
4. Save and load into Table (Ctrl+Enter).

This is the sample recipe in the builder. Records at is orders, one of the 2 arrays of records in the file, and the preview shows the result after the filter step:

The sample recipe file is short:

version = 1

[source]
kind = "json"
path = "shop-orders.json"
records = "orders"

[[step]]
op = "types"
columns = { created_at = "date:ymd" }

[[step]]
op = "filter"
column = "status"
is = "="
value = "paid"

Refresh next month

When the next export arrives, replace the file and click Refresh (Alt+F5). To pick up a new file name each month, set Each refresh reads to Newest match. Set it to All matching files to append every export in a folder, with a Source file column. See Refresh next month.

The same recipe runs without the app, for a scheduled job:

vgrid recipe run shop-orders.recipe.toml -o shop-orders.csv

./shop-orders.json (5ffb295b2671c694): 8 source rows -> 6 rows x 13 columns, ok
   1. Set types created_at: date:ymd [8 -> 8 rows, 0 ms]
   2. Keep rows where status is paid [8 -> 6 rows, 0 ms]: removed 2 rows

Details

How values come through, repeated keys, JSON Lines, and memory for large files are covered in JSON files in the import recipe guide.