JSON Input

Input

Read a JSON document or an NDJSON file and emit one row per record. Point at a nested array via dot-notation, or let the parser auto-detect the first array in the root object. Nested objects flatten to dot-notation column names by default; nested arrays serialise to JSON strings.

Local processing

This transform runs entirely in your browser. No data is sent to external servers.

How it works

JSON Input is a source node. It first tries JSON.parse on the whole file; if that fails, it falls back to NDJSON (one JSON value per line). The parser holds the full document in memory because JSON has no streamable structure short of a hand-rolled tokeniser.

Once parsed, the rootPath config selects the records array. An empty path triggers auto-detection — for top-level arrays, that array is used; for top-level objects, the first array-valued property is chosen. A non-empty path is split on . and traversed as object keys. A path that resolves to a non-array value or a missing key throws with the failing segment.

By default, each record is flattened: nested objects become dot-notation keys (e.g. address.city), and nested arrays are JSON-stringified. Recursion stops at five levels deep — keys deeper than that stay as their full dot-notation key with the raw value. Disable flattenNested to keep nested objects as-is, which downstream transforms see as untyped object cells.

Input: A .json or .ndjson file uploaded by the user. Output: A row stream where each row is a flattened (or raw) record.

Options

Option	Type	Default	Description
rootPath	string	""	Dot-notation path to the records array. Empty string auto-detects the first array. Throws if the path is missing or non-array.
flattenNested	boolean	true	Flatten nested objects into dot-notation keys, up to five levels deep. Nested arrays are always JSON-stringified.

Examples

Top-level array, flat records

A typical export of user records as a JSON array.

Before (raw file content):

[
  { "id": 1, "name": "Alice", "email": "[email protected]" },
  { "id": 2, "name": "Bob", "email": "[email protected]" },
  { "id": 3, "name": "Carol", "email": "[email protected]" }
]

Configuration: defaults — rootPath: "" (auto-detect), flattenNested: true.

After:

id	name	email
1	Alice	[email protected]
2	Bob	[email protected]
3	Carol	[email protected]

Records nested under a path, with flattening

An API response wraps the records under data.results, and each record has a nested address object.

Before (raw file content):

{
  "meta": { "fetched_at": "2025-08-15T10:00:00Z" },
  "data": {
    "results": [
      {
        "customer": "Acme Corp",
        "address": { "city": "Valencia", "country": "ES" },
        "tags": ["pro", "eu"]
      },
      {
        "customer": "Beta Inc",
        "address": { "city": "Berlin", "country": "DE" },
        "tags": ["pro"]
      }
    ]
  }
}

Configuration: rootPath: "data.results", flattenNested: true.

After:

customer	address.city	address.country	tags
Acme Corp	Valencia	ES	["pro","eu"]
Beta Inc	Berlin	DE	["pro"]

address is flattened to dot-notation columns; tags is an array, so it stays as a JSON string.

NDJSON file

One JSON object per line — common for log streams and bulk exports from databases.

Before (raw file content):

{"event":"signup","user":"[email protected]","ts":"2026-01-04T09:12:00Z"}
{"event":"login","user":"[email protected]","ts":"2026-01-04T09:14:22Z"}
{"event":"login","user":"[email protected]","ts":"2026-01-04T10:01:15Z"}

Configuration: defaults — rootPath: "", flattenNested: true.

After:

event	user	ts
signup	[email protected]	2026-01-04T09:12:00Z
login	[email protected]	2026-01-04T09:14:22Z
login	[email protected]	2026-01-04T10:01:15Z

Tips and Edge Cases

• NDJSON detection requires newlines. If standard JSON.parse fails and the file has no newline, parsing throws immediately. A single malformed JSON value cannot be rescued as NDJSON. The first non-empty NDJSON line is validated before bulk parsing — if line 1 fails, the whole file is rejected. See apps/web/src/transforms/input-json/logic.ts:121-152.
• Nested arrays always become JSON strings, regardless of flattenNested. The flatten step only descends into objects; arrays are stringified at whatever level they appear. To work with array elements as separate rows, use Unpivot or a downstream split step. See apps/web/src/transforms/input-json/logic.ts:23-53.
• Auto-detection picks the first array-valued property. When rootPath is empty and the root is an object, the parser iterates keys in insertion order and stops at the first array. If your file has multiple arrays at the root, set rootPath explicitly to avoid surprises. See apps/web/src/transforms/input-json/logic.ts:59-75.

Related Transforms

• CSV Input — read flat tabular files when the source is plain text.
• Excel Input — read .xlsx workbooks.
• Unpivot — turn a wide row into multiple long rows when JSON arrays need to become row groups.