jsonxplode

Efficient JSON flattening for complex nested structures

jsonxplode converts nested JSON structures into flat tabular format while preserving all data, including complex nested arrays and objects with arbitrary depth.

Version Update: v1.2.0

Bug fix

Relational Array Flattening - Arrays of different sizes are now also flattened relationally by default, preserving positional relationships:

Version Update: v1.1.0

Bug fix

Relational Array Flattening - Arrays of the same length are now flattened relationally by default, preserving positional relationships:

Control Relational Array Flattening

Control how arrays are flattened with the relational_array parameter:

# Default - preserves relationships between arrays
flattener = FlattenJson(relational_array=True)

# Independent flattening of arrays  
flattener = FlattenJson(relational_array=False)

Example with Relational Flattening (Default)

data = {
    "name": "John",
    "a": [1, 2, 3],
    "b": [1, 2, 3]
}
result = flattener.flatten(data)

Returns:

[
    {"name": "John", "a": 1, "b": 1},
    {"name": "John", "a": 2, "b": 2},
    {"name": "John", "a": 3, "b": 3}
]

Installation

pip install jsonxplode

Usage

from jsonxplode import flatten

# Handles any JSON structure
data = {
    "users": [
        {"profile": {"name": "John", "settings": {"theme": "dark"}, "location": ["city1", "city2"]}},
        {"profile": {"name": "Jane", "settings": {"theme": "light"}}}
    ]
}

flattened_data = flatten(data)

Returns:

[
    {'users.profile.name': 'John', 'users.profile.settings.theme': 'dark', 'user.profile.location': 'city1'},
    {'users.profile.name': 'John', 'users.profile.settings.theme': 'dark', 'user.profile.location': 'city2'},
    {'users.profile.name': 'Jane', 'users.profile.settings.theme': 'light'}
]

DataFrame Output (Optional)

from jsonxplode import to_dataframe

# Requires pandas to be installed separately
df = to_dataframe(data)

Note: to_dataframe requires pandas (pip install pandas) but the core flatten function has zero dependencies.

Features

• Arbitrary nesting depth - handles deeply nested objects and arrays
• Conflict resolution - automatically manages key path conflicts
• Memory efficient - processes large datasets with minimal overhead
• Zero dependencies - pure Python implementation (core function)
• Array expansion - properly handles nested arrays with row duplication

Performance

• 7,900 rows with 23 columns processed in 0.146 seconds
• Memory usage: ~16MB for above mentioned workload
• Consistent performance across varying data structures