How to Convert JSON to CSV: Flattening Nested Objects, Handling Arrays, and RFC 4180 Compliance

The Challenge: Hierarchical Trees vs Flat Tables

JSON represents multidimensional data trees with arbitrary nesting and variable keys, whereas CSV (Comma-Separated Values) represents two-dimensional relational tables with fixed columns. Converting JSON to CSV requires two crucial transformations: flattening deep object properties into dot-notated column headers and serializing array values deterministically.

RFC 4180 CSV Escaping Rules

To prevent Excel and automated parsers from corrupting data, every CSV generator must adhere strictly to RFC 4180:

• Quote Fields with Delimiters: If a field contains a comma (,), semicolon, or newline (\n), the entire field value must be enclosed in double quotes ("field, value").
• Escape Embedded Quotes: If a field contains a double-quote character ("), the quote must be escaped by prefixing it with another double quote (""). For example, He said "Hello" becomes "He said ""Hello""".
• CRLF Line Endings: RFC 4180 specifies \r\n as the standard row delimiter.

Flattening Nested JSON Keys (Dot Notation)

Deeply nested properties are flattened using dot-notation headers:

// Nested Input JSON:
[
  {
    "id": 101,
    "user": {
      "name": "Sarah Chen",
      "address": { "city": "Seattle", "state": "WA" }
    }
  }
]

// Flattened CSV Table:
// id,user.name,user.address.city,user.address.state
// 101,"Sarah Chen","Seattle","WA"

Handling Arrays in CSV Columns

Arrays of primitive strings (such as user tags ["developer", "admin"]) are serialized into a single column using pipe or semicolon delimiters (e.g. "developer|admin"). For arrays of nested objects, developers can choose between JSON-stringifying the cell or generating one CSV row per child entry.

Complete TypeScript & Python Converter Recipes

// RFC 4180 Compliant JSON to CSV Converter in TypeScript
export function jsonToCsv(items: Record<string, any>[]): string {
  if (!items.length) return '';
  
  // 1. Extract all unique header keys across all items
  const headers = Array.from(
    new Set(items.flatMap(item => Object.keys(item)))
  );
  
  // 2. Escape cell according to RFC 4180
  const escapeCell = (val: any): string => {
    if (val === null || val === undefined) return '';
    const str = typeof val === 'object' ? JSON.stringify(val) : String(val);
    if (/[",\n\r]/.test(str)) {
      return `"${str.replace(/"/g, '""')}"`;
    }
    return str;
  };
  
  // 3. Assemble CSV string
  const headerRow = headers.map(escapeCell).join(',');
  const rows = items.map(item =>
    headers.map(header => escapeCell(item[header])).join(',')
  );
  
  return [headerRow, ...rows].join('\r\n');
}