CSV Header Normalizer

Rename CSV column headers to a chosen case style. Pairs with every CSV Actor in this portfolio.

What it does

• Reads a CSV from inline text (csv) or a public URL (csvUrl).
• Renames all headers using one of: snake_case, camelCase, PascalCase, kebab-case, SCREAMING_SNAKE, lowercase, Title Case, preserve.
• Optional per-column override map: a {"Original Header": "exact new header"} object whose entries take precedence over the style.
• Preserves column order; preserves row order.
• Detects collisions and disambiguates by suffix (_2, _3, ...). All collisions are recorded in the SUMMARY.collisions array.
• Detects SQL-reserved generated names (select, from, where, ...) and appends _col.
• Names starting with a digit get a leading _.
• Emits one rename row per header in the dataset (with original, newName, source: 'style' | 'override', style).
• Emits the serialized output CSV in the OUTPUT key-value store and a single dataset row containing the full CSV.
• Pure JS, zero deps, no headless browser, no anti-bot risk, no login.

Allowed case styles

Style	Example
snake_case	first_name
camelCase	firstName
PascalCase	FirstName
kebab-case	first-name
SCREAMING_SNAKE	FIRST_NAME
lowercase	firstname
Title Case	First Name
preserve	(no change)

Input

Field	Type	Default	Description
csv	string	""	Inline CSV body. Leave empty to fetch from csvUrl.
csvUrl	string	""	Public URL of a CSV file. Used when csv is empty.
delimiter	string	","	Field delimiter. Use \\t for TSV.
hasHeader	bool	true	Treat first row as header. Required for normalization.
style	string	snake_case	Target case style (see table).
overrideMap	object	{}	Per-column rename override. {"First Name": "firstName"}.
maxRows	int	0	Cap on rows processed. 0 = no cap.
timeoutSec	int	30	Fetch timeout.
maxBytes	int	10000000	Fetch size cap.
eol	string	lf	lf or crlf for output line endings.

Output

• Dataset rows:
  • One rename row per header: { _kind: 'rename', index, original, newName, source, style }.
  • One output_csv row: { _kind: 'output_csv', delimiter, eol, headers, rowCount, csv }.
  • One error row on failure.
• Key-value store:
  • OUTPUT — the serialized output CSV (string).
  • SUMMARY — { ok, source, style, delimiter, hasHeader, rows, truncated, columns, originalHeaders, newHeaders, renameMap, collisions, overrideCount }.

Examples

Snake-case from inline

{
  "csv": "First Name,Last Name,E-mail Address\nAda,Lovelace,ada@example.com",
  "style": "snake_case"
}

Output headers: first_name, last_name, e_mail_address (note: the dash in E-mail splits to e + mail and joins to e_mail_address by default; use overrideMap to force email_address).

With override

{
  "csv": "First Name,LASTNAME,Phone Number",
  "style": "snake_case",
  "overrideMap": {
    "LASTNAME": "last_name",
    "Phone Number": "phoneNumber"
  }
}

Output headers: first_name, last_name, phoneNumber.

What it does not do

• It does not modify data rows; only the header row.
• It does not validate that the CSV is well-formed beyond basic parsing; pair with csv-quality-scorecard for that.
• It does not rename based on a schema; pair with csv-schema-profiler to inspect the inferred schema first.

Pairing

• Before: csv-quality-scorecard, csv-schema-profiler (inspect the existing headers + types).
• After: any of csv-dedupe-normalizer, csv-join-enricher, csv-diff, jsonl-to-csv, csv-statistical-summary.
• In an n8n/Make/Sheets pipeline: drop a "CSV Header Normalizer" step between the HTTP fetch and the consumer that expects a specific header convention.

Pricing / cost expectations

Default 256 MB / 512 MB. Streaming CSV parse; per-row cost is sub-millisecond. Pay-per-event scheduled to activate after public launch: 1 charge per header_normalized event (per column).

FAQ

Does it modify data rows? No — only the header row.

Does it handle Excel? Pre-convert to CSV. For programmatic XLSX extraction use ../xlsx-sheet-extractor.

What if a column normalizes to a duplicate? It is reported in collisions[] in the SUMMARY; the header is still emitted (de-dup is not the job of a normalizer).

Does it support Excel column names (A, B, C, AA, ...)? No, this Actor reads the existing header row.

Related Actors

• csv-delimiter-autodetect — first step if the file is not a clean comma CSV
• csv-dedupe-normalizer — dedupe rows after the header is normalized
• csv-quality-scorecard — pre-check before normalizing

Support

Open an issue on the Actor's Store page or contact via the support link in the Store listing.

License

MIT