Find the cause of a broken JSON or CSV import
An import can fail even when the file opens in a text editor. The problem may be syntax, an unexpected column, a value changed by a spreadsheet, or a mismatch between the source and destination formats. Work with a small representative sample so that each change has a result you can understand.
1. Validate JSON before changing its shape
Use the JSON formatter to locate syntax problems and make nesting readable. JSON property names and strings use double quotes. Trailing commas and comments are not part of the JSON format. Values such as true, false and null are lowercase and unquoted; “false” is a string, which is a different value from false.
When a parser reports an error near a location, inspect the surrounding characters, including the previous property. A missing comma may only become apparent when the parser reaches the next value. Use distinct property names within each object so that a duplicate key does not get interpreted differently by different systems.
[
{"sku": "00124", "name": "Blue mug", "active": true},
{"sku": "00125", "name": "Red mug", "active": false}
]Further reading: IETF RFC 8259: the JSON interchange format
2. Check CSV quoting and column boundaries
CSV needs more than splitting each line at every comma. A field containing a comma, line break or double quote must be handled as a quoted field. A literal double quote inside a quoted field is represented by two double quotes. The example below has three fields per record even though one product name contains a comma.
Check the expected delimiter and whether the first record contains column names. A file exported with semicolons is not the same input as a comma-delimited file. Inspect records with empty fields and multiline text, then verify that every record maps to the intended columns.
sku,name,note
00124,"Mug, blue","Marked ""new"""
00125,Red mug,Further reading: IETF RFC 4180: common CSV quoting conventions
3. Decide field types deliberately
A CSV field does not have a universal built-in number, date or Boolean type. Your importer decides how to interpret it. Preserve identifiers such as 00124 as strings, and use an agreed date format instead of relying on local spreadsheet defaults. Decide whether an empty field means an empty string, a missing value or a value that must be rejected.
Large numeric identifiers need particular care in browser tools. JavaScript Number cannot represent every integer beyond 9,007,199,254,740,991 exactly. Store an identifier as a quoted JSON string before parsing when its digits must remain unchanged. Adding quotes after a value has already been rounded cannot restore the original digits.
Further reading: MDN: JavaScript safe integer limits
4. Match records to a flat table
For JSON-to-CSV conversion, an array of similarly shaped objects is the simplest input: one object becomes one row and each chosen property becomes a column. Decide how nested objects and arrays should be represented before exporting. A nested shipping address might become several columns; a list of tags might need a separate table.
Do not assume a JSON → CSV → JSON round trip preserves everything. Types, missing properties, null values and nested structures can change unless both sides follow the same mapping. Compare the actual fields that the destination requires.
5. Test representative records in the destination
Include a normal record, an empty value, a comma inside a field, a non-English name and a leading-zero identifier in your sample. Convert it, inspect the result, and import that sample into the receiving application. Confirm row count, column names and exact values before processing the complete file.
Keep the source untouched until that comparison succeeds. A file that parses successfully has passed a syntax check; the destination’s field rules still determine whether the records are correct.