JSON Flattening Decision Guide
Choose records, columns and nested-value handling deliberately when turning JSON into a table.
Turning JSON into a table requires a data-model decision whenever records are nested or inconsistent.
Choose the record unit
Decide which repeated object represents one table row. A top-level response may contain metadata, pagination and records that should not be flattened together.
Choose columns deliberately
Take the union of relevant object keys and define a stable order. Missing is not necessarily the same as null, an empty string or zero.
Treat nested objects carefully
A nested address might become selected columns, a compact JSON value or a separate table. Automatic deep flattening can create unreadable headings and hide one-to-many relationships.
Protect arrays
An array in one cell needs an explicit convention. Joining values loses structure when values contain the delimiter; expanding arrays can multiply rows and change meaning.
Worked decision
For orders with several line items, make an orders table and a line-items table joined by order identifier. Repeating the full order on every item may inflate totals during later analysis.
Verify reversibility
If round-trip recovery matters, record the flattening convention and test it with nulls, missing keys, nested values and Unicode. A readable summary table is not automatically a reversible serialisation.