Back to Blog

    JsonifyTools field guide

    Can You Unflatten JSON Reliably? Delimiters, Numeric Keys, and Edge Cases

    Explore JSON flatten/unflatten round trips, delimiter collisions, numeric path segments, and the cases that need an explicit path convention.

    By JsonifyTools4 min read
    REVERSIBLE PATHS?: a.b can mean two things — delimiters need an explicit rule{ "a.b": 1 }literal dotted key?{ "a": { "b": 1 } }nested pathREVERSIBLE PATHS?a.b can mean two thingsdelimiters need an explicit rule
    A diagram illustrating delimiters need an explicit rule.

    A flat map is convenient for form state, configuration, or storage. Later, you need the original nested JSON back. The round trip works only when every flattened key has one unambiguous interpretation. Delimiters, array indexes, empty containers, and keys that contain dots can make that assumption fail.

    Try flatten and unflatten

    A round trip needs a path convention

    For a simple object, profile.name can mean the name key nested under profile. An array path might use bracket notation such as items[0].sku. A flattener and unflattener must agree about separator, array notation, escaping, and what counts as a numeric segment.

    One example path interpreted from left to right
    profileaddresses[0]city
    Flattened representation
    {
      "profile.addresses[0].city": "Pune"
    }

    If every source key avoids the chosen delimiter and the path grammar distinguishes object keys from indexes, reconstructing this example is straightforward. Real data is not always that cooperative.

    A delimiter can collide with a literal key

    Consider these two different source documents:

    One literal key

    One literal key
    { "a.b": 1 }

    Two-level path

    Two-level path
    { "a": { "b": 1 } }

    With dot notation, both can flatten to a path that looks like a.b. Without an escaping rule or a different representation, the inverse cannot know which original document to produce. Choosing underscore or slash avoids some dots but not every possible key; a source key can contain that separator too.

    Numeric segments need context

    The segment 0 might indicate array index zero or an object key named "0". Empty arrays and objects have no child paths, so a format that emits only leaves needs a marker to reconstruct them. The actual tool behavior also matters: JsonifyTools JSON Flatten supports selected separators and bracket or dot array notation, but some shapes can be ambiguous when reconstructed. Verify root arrays, numeric object keys, empty containers, and literal delimiters in your own fixtures.

    If your data contract permits arbitrary keys, a typed path representation or a reversible encoding is safer than an informal dotted string. In a controlled config format, you can instead constrain names and document the convention so producers and consumers reject ambiguous paths.

    Test representative structures before adopting it

    Fixture caseWhat to verify
    Nested objectParent and child restored
    Array of objectsIndexes and order remain
    Numeric keyObject key stays distinct from index
    Empty object / arrayContainer is not silently lost
    Key contains delimiterPath remains unambiguous

    Compare the original and reconstructed structures, not just their flattened text. Use JSON Flatten to try a convention, the JSON Viewer to inspect both trees, and the formatting guide when whitespace makes a text review harder.

    Escaping is what makes a path reversible

    A reversible path format needs a way to represent a separator that appears inside a key. Some formats escape it; others encode each segment separately or store typed path arrays. Switching from dot to slash only moves the collision unless the allowed key alphabet is constrained. If the format has no escaping rule, do not assume every input can round-trip.

    Compare parsed structures, not serialized strings

    After unflattening, parse both documents and compare their nested values under the rules your application cares about. Whitespace and object member order may differ even when the structures match. Include root arrays and scalar roots in tests if your pipeline permits them; many flattening conventions are designed around object roots and need an explicit rule for other JSON values.

    Tags

    • JSON flatten and unflatten
    • unflatten nested JSON
    • JSON dot notation keys
    • JSON delimiter collision
    • JSON array index notation
    • flat keys to nested object
    • reversible JSON paths
    • JSON transformation