json-normalize

What it is and what it does

json_normalize takes a nested JSON-like structure—dicts, lists, generators, and other iterables—and flattens it into a sequence of flat dictionaries. Each key in the output is a dot-joined path from the root to a leaf value. The package handles the tricky case of data association: when nested dicts share a common dict ancestor, their data flows together into the same output records; when they share a list ancestor, they remain separate. When multiple independent lists exist in different branches, you can choose how to combine them: chain them sequentially, compute their Cartesian product, or drop problematic branches entirely.

The function is configurable: you can customize the path joiner (dot, arrow, or a callable), freeze certain nodes to prevent recursive normalization below them, drop nodes by name, and control list combination behavior. It accepts generators and lazy iterables as input, making it useful for streaming or memory-constrained scenarios.

Use it for:

• Convert API responses with nested objects and arrays into flat rows suitable for CSV export or database insertion
• Flatten configuration files or metadata structures to extract all leaf values with their full paths
• Denormalize time-series data where measurements contain nested sensor readings and metadata
• Transform hierarchical log entries or event objects into tabular format for analysis
• Prepare nested JSON for pandas DataFrame construction by generating flat dict records

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Recursively flattens nested JSON-like structures (dicts and iterables) into a sequence of flat dictionaries with dot-joined keys, handling multiple lists through configurable combination strategies.

Yes, if you need to flatten nested JSON into flat dicts. The package is stable, dependency-free, and permissively licensed. Dormant maintenance is acceptable for a focused utility with no known vulnerabilities, but verify it handles your specific nesting patterns (especially multiple list branches) before committing to production use.

Install

json-normalize on PyPI

pip install json-normalize

uv add json-normalize

poetry add json-normalize

Installing json-normalize

Before you install

Low friction: pure Python wheel with no runtime dependencies. Maintenance is dormant (last commit 2024-09-25, 869 days since release), but the package is marked Production/Stable and has received no security reports.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal attribution requirements—suitable for any project type.

Quickstart

from json_normalize import json_normalize

json_like = {"city": "Stockholm", "coords": {"lat": 59.331924, "long": 18.062297}}
result = list(json_normalize(json_like))
# Output: [{'city': 'Stockholm', 'coords.lat': 59.331924, 'coords.long': 18.062297}]

Verify before relying

• Whether dormant maintenance status (869 days since last release) poses a risk for future Python or dependency ecosystem changes
• Performance characteristics on deeply nested or very large JSON structures

Package facts

Evidence: json_normalize-1.1.0-py3-none-any.whl

Keywords: JSON

Tags

More Libraries packages