About

Incorrect data format conversion between Excel spreadsheets and JSON causes silent failures in data pipelines, misconfigured game assets, and broken API integrations. A single mistyped cell or wrong column type annotation can propagate NULL values across thousands of records. This converter parses .xlsx files entirely in your browser, interpreting header-row type annotations (#string, #number, #bool, #date, #[], #{}, #id) to produce structured JSON. It handles master-slave sheet relationships where complex columns are split into separate sheets, resolving foreign key references via #id and #id[] columns. Output format is determined automatically: a JsonHash keyed by the #id column when present, or a JsonArray otherwise. The tool approximates the xlsx2json specification assuming well-formed XLSX files exported from Excel, Google Sheets, or LibreOffice. Sheets prefixed with ! and columns prefixed with ! are excluded from output.

Formulas

The converter determines output format based on header annotations. The decision logic follows:

{

JsonHash if column with #id existsJsonArray otherwise

For JsonHash output, each row is keyed by its #id value: output[row_id] = rowObject. For master-slave resolution, the slave sheet name follows the pattern slaveName@masterName. If the slave contains a #id column, each slave row merges into the corresponding master row as a nested object. If the slave contains a #id[] column, slave rows with matching IDs are grouped into an array under the master row.

Type coercion for auto-detected cells without explicit annotation uses the rule chain: if the value matches parseFloat(v) ≠ NaN → number. If v ∈ {TRUE, FALSE, true, false} → boolean. If v = "" → null. Otherwise → string.

Reference Data

Type Annotation	Header Format	Description	Example Cell Value	JSON Output
#string	name#string	Force string type	123	"123"
#number	age#number	Force numeric type	25	25
#bool	active#bool	Boolean type	TRUE	true
#date	created#date	Date string (ISO format)	2024/1/15	"2024-01-15"
#[]	tags#[]	Array (JS literal syntax)	["a","b","c"]	["a","b","c"]
#{}	config#{}	Object (JS literal syntax)	{key:"val"}	{"key":"val"}
#id	id#id	Primary key → hash output	1001	Key in hash map
#id[]	id#id[]	FK array (slave sheets only)	1001	Grouped under master ID
! prefix	!notes	Skip column (not exported)	Any	Excluded
(auto)	score	Auto-detect: number, bool, string	99.5	99.5
Sheet !	!draft	Skip entire sheet	-	Excluded
Slave sheet	items@master	Slave linked to master sheet	-	Merged into master
null	Any	Empty cell	(empty)	null

Frequently Asked Questions

When a column header includes the #id annotation (e.g., id#id), the output switches from a JSON array to a JSON hash (object). Each row's #id value becomes a key in the top-level object, and the row data becomes its value. Only one #id column is permitted per sheet. Without it, rows are output as an ordered array.

Columns annotated with #[] or #{} expect cell values written in JavaScript literal syntax (not strict JSON). For example, [1,2,3] or {name:"test",value:42}. The converter evaluates these using a safe parser. If parsing fails, the cell value falls back to null and a warning is displayed. Always use English half-width symbols for brackets, colons, and commas.

A slave sheet is named using the pattern slaveName@masterName. The master sheet must appear before the slave in the workbook and must contain a #id column. The slave sheet must also have either a #id column (for merging as a nested object into the master row) or a #id[] column (for grouping slave rows into an array under the master row). This allows complex nested structures to be spread across multiple readable sheets.

This occurs when Excel retains formatting or invisible data in rows below your actual content. The cells appear empty but are not truly blank in the file. Check the row count displayed by the converter against your expected data count. You can clean this in Excel by selecting the empty rows, right-clicking, and choosing Delete (not just clearing contents).

The converter reads Excel's internal date serial number and converts it to an ISO date string. If Excel stores the value as a formatted date string instead (common in some locales), standard formats like YYYY/M/D, YYYY-MM-DD, and YYYY/M/D H:m:s are recognized. Non-standard date strings that cannot be parsed will output as plain strings with a console warning.

Yes. Prefix any column header with ! (e.g., !notes) to exclude that column from the JSON output. Prefix any sheet name with ! (e.g., !draft) to skip the entire sheet during conversion. This is useful for keeping internal comments or work-in-progress data in the spreadsheet without polluting the export.