Nested JSON to CSV: How Dot Notation Flattening Works

When you paste nested JSON into the WildandFree JSON to CSV converter, nested objects are automatically flattened using dot notation. A field like address.city becomes its own CSV column — no preprocessing required. You get a clean, flat spreadsheet from a multi-level JSON structure in one step.

Here's exactly how the flattening works, what it handles, and where the limits are.

What Dot Notation Flattening Means for Your CSV

Consider this JSON object:

{
  "name": "Alice",
  "address": {
    "city": "Denver",
    "state": "CO"
  }
}

A naive converter would either skip the nested address object or dump it as a raw string like {"city":"Denver","state":"CO"} into one cell — both useless in a spreadsheet.

Dot notation flattening expands nested objects into separate columns using the key path as the column name. The above becomes:

name,address.city,address.state
Alice,Denver,CO

Each nested field gets its own column. The column header reflects where in the JSON structure the value came from. This is readable, filterable, and sortable in Excel, Google Sheets, or any CSV-compatible tool.

Multi-Level Nesting — How Deep It Goes

The converter handles multiple levels of nesting. A three-level deep object like this:

{
  "user": {
    "profile": {
      "firstName": "Bob"
    }
  }
}

becomes the column header user.profile.firstName. The dots just keep chaining for each level of nesting. In practice, most APIs return one or two levels of nesting — three or more is unusual but supported.

The important thing: each nested key at any depth becomes its own column in the output. If your JSON array of 50 objects all have the same nested structure, the converter infers all columns from the first few rows and applies them consistently across the entire dataset.

Sell Custom Apparel — We Handle Printing & Free Shipping

What Dot Notation Cannot Handle: Nested Arrays

Dot notation handles nested objects well. Nested arrays are a different problem.

If your JSON looks like this:

{
  "orderId": 101,
  "items": [
    {"product": "Hat", "qty": 2},
    {"product": "Shirt", "qty": 1}
  ]
}

The items array is a one-to-many relationship that a flat CSV cannot represent without repeating the parent row for each item. The converter will either skip the array or serialize it as a string — neither is ideal.

For this type of data, you have two options before converting:

• Flatten manually — rewrite the JSON so each item is a top-level object with orderId repeated: [{"orderId":101,"product":"Hat","qty":2}, {"orderId":101,"product":"Shirt","qty":1}]
• Use a code-based tool — Python's pandas.json_normalize() with the record_path parameter handles this properly

For flat arrays of objects (no nested arrays), the browser tool works perfectly. For data with nested arrays, a quick script is the more appropriate choice.

Step by Step: Paste and Convert Nested JSON

1. Open the JSON to CSV converter
2. Paste your JSON array. Make sure it is an array of objects: the outermost structure should be [{...}, {...}]. If you have a single object, the tool wraps it automatically.
3. Select your delimiter (comma is standard, tab works well for data going into Excel)
4. Click Convert — the flattened CSV appears instantly
5. Click Copy to clipboard or Download to save the .csv file

The column headers in the output follow dot notation: user.name, user.address.city, etc. These are valid CSV headers — you can rename them in Excel after import if needed.

For large JSON payloads (10,000+ rows), the conversion still runs locally in your browser. Processing happens using your device's compute — no upload, no server round trip, no timeout.

Real-World Examples: What Gets Flattened

Common sources of nested JSON that the converter handles cleanly:

• API responses — REST APIs commonly return nested user objects: user.id, user.email, user.address.city. These flatten to readable columns.
• MongoDB exports — MongoDB documents often nest sub-documents. Exporting as JSON and converting to CSV with dot notation flattening makes the data usable in Excel.
• Google Analytics exports — GA4 exports JSON with nested dimension and metric objects. Flattening these to CSV makes them filterable in Sheets.
• CRM exports — HubSpot, Salesforce, and similar CRMs export contact data with nested company and address objects. The flattened CSV is ready to import into any CRM or analytics tool.

After converting, related tools for working with the resulting CSV: CSV column mapper for renaming dot-notation headers to clean labels, and CSV deduplicator for removing duplicate rows that can result from a flattening operation.

Frequently Asked Questions

Does the converter handle deeply nested JSON (3 or more levels)?

Yes. The tool recursively flattens nested objects at any depth. A three-level key like user.address.postalCode becomes a single column header. Very deep nesting (5+ levels) produces long column names but is handled correctly.

What happens to null values in nested JSON?

Null values are preserved as empty cells in the CSV. If a nested field is null, the corresponding dot-notation column gets an empty value for that row.

Can I rename dot-notation column headers after conversion?

Yes — the CSV file can be opened in Excel or Google Sheets where you can rename any column header. Alternatively, use the CSV column mapper tool to rename columns without opening a spreadsheet application.

My JSON has mixed structure — some objects have nested fields, others don't. What happens?

The converter handles sparse data. If some rows have a nested field and others don't, the column still appears in the CSV — rows without that field get an empty cell for that column.