JSON Flatten and Unflatten Utilities

0.3.1 · active · verified Tue Apr 14

json-flatten is a Python library providing functions to convert a nested JSON object into a single-level dictionary of key-value pairs, and to reconstruct the original JSON object from that flattened representation. It's particularly useful for scenarios like converting JSON for HTML forms or query string parameters. The library is actively maintained, with releases typically addressing bug fixes and minor enhancements. The latest version is 0.3.1.

Warnings

breaking Starting from version 0.3, the `flatten()` function now explicitly checks if the input object is a dictionary. If a non-dictionary object (e.g., a list or a string) is passed, it will raise a `TypeError`.
Fix: Ensure that the input to `flatten()` is always a dictionary. If you need to flatten a list of dictionaries, iterate over the list and flatten each dictionary individually.
breaking Version 0.2 introduced a change in the serialization format used for array keys. This update correctly handles dictionaries where keys are strings containing only digits. This means data flattened with versions prior to 0.2 might not unflatten correctly with 0.2 and later, or vice-versa, if such array keys are present.
Fix: If working with existing flattened data, verify its compatibility with the current `json-flatten` version. Consider re-flattening old data with the new version if issues arise.
gotcha The library uses a specific and detailed format for flattened keys, especially for array elements (e.g., `parent.array.[index]$type=value`) and includes type hints for round-tripping complex types like `None`, `True`/`False`, `int`, `float`, and `str`. While this ensures accurate unflattening, it differs from simpler flattening schemes and requires careful consideration if manually manipulating keys or integrating with other flattening tools.
Fix: Refer to the library's documentation, particularly the 'flattened format' section, to understand the exact key representation if you intend to process or generate flattened data outside of the `json-flatten` library.

Install

pip install json-flatten Install with pip

Imports

flatten
```
from json_flatten import flatten
```
The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.
unflatten
```
from json_flatten import unflatten
```
The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.

Quickstart

This example demonstrates how to flatten a nested dictionary (representing a JSON object) into a flat dictionary using `flatten()`, and then restore it to its original nested structure using `unflatten()`.

from json_flatten import flatten, unflatten

original_json = {
    "name": "Alice",
    "details": {
        "age": 30,
        "address": {
            "street": "123 Main St",
            "city": "Anytown"
        },
        "hobbies": ["reading", "coding", {"sport": "swimming"}]
    },
    "active": True
}

# Flatten the JSON object
flattened_data = flatten(original_json)
print("Flattened Data:", flattened_data)
# Expected output for flattened_data might look like:
# {
#     'name': 'Alice',
#     'details.age': 30,
#     'details.address.street': '123 Main St',
#     'details.address.city': 'Anytown',
#     'details.hobbies.[0]$str': 'reading',
#     'details.hobbies.[1]$str': 'coding',
#     'details.hobbies.[2].sport': 'swimming',
#     'active': True
# }

# Unflatten the data back to its original structure
unflattened_json = unflatten(flattened_data)
print("Unflattened Data:", unflattened_json)

# Verify round-trip (optional)
assert original_json == unflattened_json

view raw JSON →