A spreadsheet is not a schema

Each row becomes an object and the header row supplies the keys. Simple — and the consequence is that whatever somebody typed at the top of a column is now a field name in your data.

That is a design decision, and it is usually made by accident.

Why the header row matters more than it looks

Headers are written for people to read. So they contain spaces (First Name), capitals, punctuation, units in brackets (Salary (USD)), sometimes a trailing space, occasionally a line break.

As JSON keys those are awkward in a way that persists forever:

• A key with a space cannot be reached with dot notation in most languages — it is obj["First Name"] from then on, everywhere.
• A trailing space produces a key that looks identical to the one you expect and is not, which is among the more frustrating bugs to find because the two are visually indistinguishable in a debugger.
• Punctuation and units make keys that differ between exports, so code written against one file breaks on the next.

The fix is upstream and it is cheap: rename the headers in the sheet, once, before exporting. Lower case, underscores for spaces, units dropped from the name — salary_usd rather than Salary (USD). Doing it in the sheet takes a minute; doing it in code means transforming keys on every import for the life of the project.

Four structural problems to fix before converting

• Duplicate headers. Two columns with the same name cannot both become the same key. One wins, or the second gets renamed — either way you cannot rely on which, so make them distinct in the sheet.
• Blank headers. An empty header cell has no name to become, so you get an empty or generated key that nothing in your code will be expecting.
• Merged header cells. A header spanning several columns does not survive as a sensible key for any of them.
• Rows above the header. A title, a note, a logo — anything above the real headings shifts the header row down, so the first data row is read as the field names and your keys become somebody's title text.

All four are five-minute fixes in the spreadsheet and ongoing irritations in code, which is the argument for doing them in the spreadsheet.

Types and empty cells

Numbers and dates come through typed rather than as strings, which is the advantage of reading the workbook directly rather than going via CSV — the workbook actually records what each cell is.

Empty cells become null rather than being left out of the object. That distinction is worth noticing: a key present with a null value and a key absent altogether behave very differently in code, and getting a consistent shape from every row is generally what you want when the destination is a database or an API.

Why convert at all

Seeding a database, feeding a script, building test fixtures, or taking data that colleagues collected in a spreadsheet into a system that needs structure.

That last one is the common case and it is worth defending: a spreadsheet is often the right tool for collecting data and the wrong one for storing it. People who will never use a form or a database will happily fill in a sheet, and converting is how that work becomes usable without asking them to change how they work.

Everything runs in your browser and nothing is uploaded. If the destination only needs a flat table rather than structured objects, the XLSX to CSV converter is the simpler route.