CSV Headers as JSON Keys

Using CSV Headers as JSON Object Keys

The header row in a CSV file defines the structure of the resulting JSON objects. Getting header parsing right is critical for producing clean, usable JSON output.

Example with clean headers

firstName,lastName,email
John,Doe,john@example.com
Jane,Smith,jane@example.com

Produces:

[
  { "firstName": "John", "lastName": "Doe", "email": "john@example.com" },
  { "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com" }
]

Common header problems and solutions

1. Whitespace in headers

Many CSV files contain spaces around header names, especially those exported from spreadsheets:

 First Name , Last Name , Email

Always trim headers before using them as keys. " First Name " should become "First Name" or, better yet, "firstName" after normalization.

2. Duplicate headers

name,age,name
Alice,30,Smith

When headers repeat, parsers must decide how to handle collisions. Common strategies include appending a numeric suffix (name, name_2) or using only the last value. There is no universal standard.

3. Special characters in headers

Headers like "Order #", "Price ($)", or "Créé le" are valid in CSV but can cause issues when used as JSON keys. Consider normalizing to camelCase or snake_case:

"Order #"     → "orderNumber"
"Price ($)"   → "priceUsd"
"Créé le"     → "creeLe" or "createdAt"

4. Empty headers

Some CSV files have trailing commas that create unnamed columns. Parsers should either ignore these columns or assign generated names like "column_4".

Best practices

• Trim all whitespace from headers
• Normalize casing for consistency (camelCase is common for JSON)
• Handle duplicates with a deterministic suffix strategy
• Validate that every data row has the same number of fields as the header