Why Arrays Disappear When You Flatten and Unflatten JSON

Guide · Last verified Aug 19, 2026

It's easy to expect that flattening JSON and then unflattening it back will give you something identical to the original. But if the JSON contained arrays, that expectation breaks. This guide pinpoints exactly where and how information disappears in the flatten-unflatten round-trip, based on the actual implementation of the JSON flattener.

1. How flattening works

Flattening turns nested objects into single-level keys joined by a dot (.) separator. {"user":{"name":"Alice"}} becomes {"user.name":"Alice"}. Arrays are handled using the index as part of the key: {"tags":["a","b"]} becomes {"tags.0":"a","tags.1":"b"}, and if there's an object inside an array, that object is recursively flattened further too.

2. What actually happens on unflatten: arrays become objects

Here's the crux. The unflatten logic walks each dot-split key fragment in order and always creates a plain object ({}) to fill values into. There's no logic to judge whether something was an array. So unflattening {"tags.0":"a","tags.1":"b"} produces not {"tags":["a","b"]} but {"tags":{"0":"a","1":"b"}} — an object with keys "0", "1", not an array. In JSON these two look the same by value (both hold "a", "b" in order) but differ in type, so anyone about to handle this result in JavaScript code with .map() or .length hits an error immediately.

3. Why it's built this way — "array or object" is a question with no answer

This is less a bug than a choice about an ambiguous question. From the flattened keys {"list.0":"x","list.1":"y"} alone, there's no way to be 100% sure whether this was originally an array or an object that happened to have keys "0", "1". You could use a heuristic — "treat consecutive integers starting from 0 as an array" — but this tool doesn't make that guess at all and instead chooses to always unify to objects, handling it safely (without ambiguity). Implementation gets simpler, at the trade-off that JSON containing arrays changes structure after the round-trip.

4. 2D arrays: not split any further

An array inside an array ([[1,2],[3,4]]) is one step more different. When inspecting an array element, the flatten logic recurses further "only when this element is an object and not an array." If the element itself is an array it doesn't meet this condition, so it stores that array unsplit, as the original, as the value of the index key.

As a result this value still keeps its array type even inside the flat structure serialized by JSON.stringify. And when you feed this value back into unflatten, the top-level value ([1,2] itself) is carried over keeping its original array type, so this part of the round-trip isn't broken — the broken point is strictly the 1D array part that had been "scattered across multiple index keys."

5. Other information loss: when a key contains the separator

If a field name in the original data happens to contain the separator (default dot), you get a problem. For example, if the field name really is "a.b", after flattening there's no way to tell whether it was originally one key or the b field inside an a object. This tool has no separate escaping rule, so when handling such data the practical solution is to change the separator input in the UI to a character other than a dot (e.g. / or _) to avoid the collision. Conversely, an empty object {} and an empty array [] are preserved wholesale as values during flattening (no child keys are created), so these two cases come back exactly as the original after unflattening.

Frequently Asked Questions