{"id":5978,"library":"json-flatten","title":"JSON Flatten and Unflatten Utilities","description":"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.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/simonw/json-flatten","tags":["json","flatten","unflatten","data transformation","nested"],"install":[{"cmd":"pip install json-flatten","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.","wrong":"from json_flatten.json_flatten import flatten","symbol":"flatten","correct":"from json_flatten import flatten"},{"note":"The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.","wrong":"from json_flatten.json_flatten import unflatten","symbol":"unflatten","correct":"from json_flatten import unflatten"}],"quickstart":{"code":"from json_flatten import flatten, unflatten\n\noriginal_json = {\n    \"name\": \"Alice\",\n    \"details\": {\n        \"age\": 30,\n        \"address\": {\n            \"street\": \"123 Main St\",\n            \"city\": \"Anytown\"\n        },\n        \"hobbies\": [\"reading\", \"coding\", {\"sport\": \"swimming\"}]\n    },\n    \"active\": True\n}\n\n# Flatten the JSON object\nflattened_data = flatten(original_json)\nprint(\"Flattened Data:\", flattened_data)\n# Expected output for flattened_data might look like:\n# {\n#     'name': 'Alice',\n#     'details.age': 30,\n#     'details.address.street': '123 Main St',\n#     'details.address.city': 'Anytown',\n#     'details.hobbies.[0]$str': 'reading',\n#     'details.hobbies.[1]$str': 'coding',\n#     'details.hobbies.[2].sport': 'swimming',\n#     'active': True\n# }\n\n# Unflatten the data back to its original structure\nunflattened_json = unflatten(flattened_data)\nprint(\"Unflattened Data:\", unflattened_json)\n\n# Verify round-trip (optional)\nassert original_json == unflattened_json","lang":"python","description":"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()`."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=0.3"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}