json-flattener

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 on this page — 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

json-flattener on PyPI

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

Evidence: json_flattener-0.1.9-py3-none-any.whl

Keywords: linkml, data-science, denormalization, yaml, json, data-frames

Tags

More Bio-Informatics packages