Converting JSON to CSV: Handling Nested Objects and Arrays

CSV remains the lingua franca of data exchange for spreadsheets, databases, and analytics tools. Converting flat JSON to CSV is straightforward, but nested objects and arrays present real challenges. You have two options: flatten with dot notation or serialize nested values as JSON strings.

Strategies for Nested Data

Dot notation flattening (e.g., "user.address.city") works well for 1-2 levels of nesting. For deeper structures, serialize nested values as JSON strings in a single CSV cell. Arrays can be joined with semicolons for simple values, or serialized as JSON for complex objects. Always handle edge cases: commas in values, quotes, newlines, and inconsistent keys across objects.

Why This Matters in 2026

JSON remains the dominant data interchange format in 2026, powering REST APIs, configuration files, NoSQL databases, and microservice communication. Every developer interacts with JSON daily, yet subtle formatting and validation issues continue to cause production bugs. Understanding JSON deeply — beyond just reading and writing it — is what separates reliable systems from fragile ones. As AI-generated JSON becomes more common, validation and schema checking have shifted from nice-to-have to absolutely essential.

Key Takeaways

• Always validate JSON at system boundaries using both syntax and schema validation
• Use 2-space indentation for development; minify for production payloads automatically
• Handle nested structures with dot notation flattening or JSON string serialization
• Never use trailing commas, single quotes, or unquoted keys — they break JSON parsing
• Use streaming parsers like Oboe.js for files larger than 10MB to avoid memory issues
• Leverage JSON Schema (draft 2020-12) for structural validation in production systems

Common Mistakes to Avoid

• Using trailing commas — valid in JavaScript but invalid in JSON
• Using single quotes instead of double quotes for strings and keys
• Leaving keys unquoted — { name: "value" } is invalid JSON
• Not wrapping JSON.parse in try-catch, causing uncaught SyntaxError exceptions
• Trusting AI-generated JSON without running schema validation on the output
• Sending minified JSON to logs, making debugging nearly impossible

Best Practices

• Format JSON during development; minify in production via build tools
• Validate at every system boundary — API responses, file imports, user input
• Use JSON Schema for structural validation in production systems
• Handle large files with streaming parsers or JSONL format
• Use consistent key ordering with a formatter for cleaner git diffs
• Document your JSON schemas and share them with API consumers via OpenAPI

Quick Reference

Here is a quick reference for the most common JSON operations in JavaScript. These patterns cover parsing, formatting, minifying, and safe error handling:

// Parse JSON safely
function safeParse(str) {
  try {
    return { ok: true, data: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e.message };
  }
}

// Format JSON with 2-space indentation
const formatted = JSON.stringify(obj, null, 2);

// Minify JSON for production
const minified = JSON.stringify(obj);

// Deep clone via JSON (loses functions, dates, undefined)
const clone = JSON.parse(JSON.stringify(original));

Real-World Example

Consider an API endpoint that receives user data from a third-party service. The response might be malformed, contain unexpected types, or have missing fields. Here is how to handle it safely with proper validation at every step:

async function fetchUserData(userId) {
  const res = await fetch(`/api/users/${userId}`);
  const text = await res.text();

  const parsed = safeParse(text);
  if (!parsed.ok) {
    throw new Error(`Invalid JSON: ${parsed.error}`);
  }

  const user = parsed.data;
  if (typeof user.id !== "number" || typeof user.email !== "string") {
    throw new Error("Schema validation failed");
  }

  return user;
}

Tools and Resources

• DevKit JSON Formatter — browser-based, no data sent to servers
• DevKit JSON Validator — catches syntax errors with line and column numbers
• JSON Schema Validator — structural validation against a defined schema
• jq — command-line JSON processor for filtering and transforming data
• DevKit JSON to CSV — convert JSON data for spreadsheet analysis

"JSON is the duct tape of the internet. It is not elegant, but it holds everything together."

JSON is fundamental to modern web development, and mastering its nuances saves hours of debugging time. Always validate at system boundaries, format during development, minify for production, and use schema validation for critical data. With the right tools and practices, JSON becomes a reliable foundation rather than a source of bugs.