Skip to content
jsoncsvonline

How to Convert CSV to JSON with Nested Structure

Published

Convert CSV to JSON online or with code: rebuild dotted headers into nested objects, handle array brackets, infer types accurately, and export clean JSON.

Quick answer

To convert CSV to JSON, parse the header row to extract property names, map each subsequent row into a key-value object, and infer basic types (numbers, booleans, and nulls). To reconstruct nested JSON hierarchies rather than flat strings, treat dotted headers (like customer.name) as nested object paths and bracketed headers (like items[0]) as array indices. You can run this conversion locally without server uploads using our free CSV to JSON converter.

Input CSV vs. Reconstructed JSON

Source CSV with dotted headers

order_id,customer.name,customer.city,items.0.sku,items.0.qty,status
8841,Ada Lovelace,London,DEV-01,2,delivered
8842,Charles Babbage,London,DEV-02,1,shipped

Clean JSON result with nested objects & arrays

[
  {
    "order_id": 8841,
    "customer": {
      "name": "Ada Lovelace",
      "city": "London"
    },
    "items": [
      { "sku": "DEV-01", "qty": 2 }
    ],
    "status": "delivered"
  },
  {
    "order_id": 8842,
    "customer": {
      "name": "Charles Babbage",
      "city": "London"
    },
    "items": [
      { "sku": "DEV-02", "qty": 1 }
    ],
    "status": "shipped"
  }
]

Most basic converters leave the dots in the keys (producing {"customer.name": "Ada Lovelace"}). Our engine recursively expands paths into real object and array trees matching your API schemas.

How nesting and type inference work

1. Dotted path reconstruction

A header called user.profile.bio splits on dots to create { "user": { "profile": { "bio": "..." } } }. If you prefer flat keys, nesting reconstruction can be disabled with a single toggle in our converter settings.

2. Bracket notation for arrays

Headers containing numeric brackets like tags[0], tags[1] or items[0].name are parsed into ordered arrays of primitives or objects.

3. Intelligent type inference

CSV stores everything as raw text. During conversion, values are evaluated:

  • Numbers: Strings like "42" or "-3.14" convert to numbers.
  • Booleans & nulls: "true", "false", and "null" convert to boolean and null literals.
  • Leading zeros & identifiers: Strings like "01234" (zip codes) or "+14155550199" (phone numbers) stay strings to prevent information loss.
  • Strict string mode: If you want all values preserved as strings without casting, type inference can be toggled off entirely.

Output shape options

Depending on where you plan to load the resulting JSON, you can choose:

  1. Array of objects (default): Standard JSON document suitable for REST API endpoints and state stores.
  2. JSON Lines (JSONL / NDJSON): One JSON record per line, ideal for streaming into BigQuery, Elasticsearch, or log aggregators.
  3. Keyed object / lookup table: Key the entire dataset by a specific unique ID column (e.g., indexed by order_id).

Programmatic conversion in Python

import csv
import json

records = []
with open("data.csv", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for row in reader:
        records.append(row)

with open("data.json", "w", encoding="utf-8") as f:
    json.dump(records, f, indent=2)

Note: Python’s standard csv.DictReader leaves all values as strings and does not reconstruct dotted headers into nested dictionaries. The Code tab in our CSV to JSON Converter generates a custom script that handles inference and nested reconstruction automatically.

Related tools & guides