---
id: json-flattener
version: "0.1.9"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# json-flattener — Python library for denormalizing nested dicts or json objects to tables and back

License: permissive · Maintenance: dormant · Downloads: 301.8K/mo

## What it is and what it does

json-flattener transforms nested JSON, YAML, or JSON-Lines data into flat tabular rows where each top-level key becomes a column. Nested objects are flattened by concatenating keys with underscores (e.g., creator.name becomes creator_name), and lists of objects are converted into parallel lists within cells. The library also supports serializing complex fields as embedded JSON or YAML strings, and can reverse the process to reconstruct the original nested structure from flattened data.

The primary use case is preparing normalized data models for tools that expect tabular input: Pandas dataframes, Excel, SQL databases, Solr/Lucene indexes, or Unix text processing. It ships with a command-line tool (jfl) for batch operations and can be used programmatically from Python. The package depends only on click and pyyaml, making it lightweight to install.

Use it for:

- Export nested API responses or document databases to CSV/TSV for analysis in spreadsheets or Pandas.
- Prepare hierarchical YAML configuration or data files for indexing in Solr or Lucene.
- Convert complex Python objects to flat rows for import into SQL databases without manual schema design.
- Denormalize LinkML or other schema-driven data for downstream data science workflows.
- Round-trip nested data through tabular formats while preserving the ability to reconstruct the original structure.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts nested JSON/YAML objects into flat tabular rows suitable for dataframes, spreadsheets, or databases, with the ability to round-trip back to the original structure.

Yes, if you need to flatten nested JSON/YAML to tabular format and can tolerate dormant maintenance. The package is stable, has no known vulnerabilities, installs with minimal friction, and solves a specific problem well. However, do not expect active development or bug fixes—evaluate whether the current feature set meets your needs before committing to a dependency.

## Install

pip install json-flattener
uv add json-flattener
poetry add json-flattener

## Installing json-flattener

Before you install: Low friction: pure Python wheel with only click and pyyaml as runtime dependencies. Maintenance is dormant—last release was 2022-02-26 and no commits since 2024-03-21—so expect no active bug fixes or feature development.

License in practice: BSD permissive license means you can use, modify, and distribute the package freely in commercial or private projects with minimal restrictions.

Quickstart:

pip install json-flattener

from json_flattener import Flattener

flattener = Flattener()
flat_rows = flattener.flatten([{"id": "1", "creator": {"name": "Author"}}])

Requires Python 3.7 or later.

Verify before relying:

- Whether the library handles deeply nested structures beyond one level of flattening (description mentions 'currently one level' but scope unclear).
- Performance characteristics on large datasets or whether there are memory constraints.
- Whether unflatten operation preserves all data fidelity in round-trip scenarios.

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 301.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

flatten nested json to table, denormalize json objects, json to dataframe, nested structure to rows, yaml flattening, json denormalization, complex objects to tabular format, data-transformation, json-processing, tabular-conversion

[View on SkillFed](https://skillfed.io/packages/json-flattener) · [View on PyPI](https://pypi.org/project/json-flattener/)