JSON dot notation for flattening and rebuilding data
How dot-notation keys encode a path through nested JSON, why array indexes appear as numbers, and how to unflatten safely.
What a dot-notation key encodes
A flat key such as user.address.city is really a set of directions for walking down a nested structure. Each segment between the delimiters names one step: first the user object, then its address object, then the city value inside it. Flattening reads every path from the root down to a leaf and records it as one key with its value, so a tree of objects becomes a simple lookup table. This form is handy for diffing two JSON documents, for building form field names, and for feeding config values into systems that only accept flat key and value pairs.
Numbers mean array positions
When a segment is made entirely of digits, it represents an array index rather than an object key. That is why the first element of a tags array flattens to tags.0 and not to some named property. The convention lets a single flat map describe both objects and arrays without any extra metadata. On the way back, the unflatten step checks each segment: if it is all digits it creates or extends an array, and otherwise it creates an object, so the original mix of maps and lists is reconstructed from the keys alone.
Choosing a delimiter that is safe
The dot is the default because it reads naturally, but it is only safe when your real keys never contain a dot themselves. If a key legitimately includes a dot, a version string or a domain name for example, the flattener cannot tell that dot apart from a path separator, and unflatten will split the key in the wrong place. The Delimiter field exists for exactly this case: pick a character such as a slash, a pipe or a double underscore that you know will not appear inside any key, and use the same one in both directions.
Round trips and their limits
For clean, well-formed JSON the flatten and unflatten pair is lossless, so you can move data out to a flat shape, edit it, and rebuild the tree exactly. The edges to watch are sparse arrays and keys that collide once flattened. If you flatten an array that skips indexes, rebuilding it leaves empty slots where the missing indexes were. And if two different structures would produce the same flat key, the last value written wins. Keeping keys unique and array indexes contiguous means a round trip always returns what you started with.