JSON Flattening vs Normalization: When Each Approach Helps
Reviewed September 3, 2026 · Maintained by William
Flattening and normalization both change data shape, but they solve different problems. Flattening turns nested paths into keys. Normalization reorganizes data around entities or repeated structures so they can be referenced consistently.
Flattening example
{
"user": {"name":"Ada","address":{"city":"Lahore"}}
}A simple dot-path flattening may become:
{
"user.name": "Ada",
"user.address.city": "Lahore"
}This is useful for CSV columns, form field names, environment-style configuration and line-by-line comparisons.
Normalization example
Imagine an API response contains the same author object under many posts. A normalized structure may store authors once by ID and let posts reference the author ID. That reduces duplication and can make updates easier in client state or a database.
Flattening risks
- A source key that already contains the delimiter can become ambiguous.
- Numeric object keys can be confused with array indexes during unflattening.
- Empty arrays/objects may need explicit representation if a round trip must preserve them.
Normalization risks
- You need stable identity keys.
- Reconstructing the original nested response requires joins/lookups.
- Normalization can be unnecessary complexity for one-off export or debugging tasks.
When to choose each
Flatten when your destination is table-like, path-oriented or easier to compare as scalar fields. Normalize when your application repeatedly manipulates entities and relationships.
The JSON Flatten & Unflatten tool intentionally treats flattening as a convention and exposes delimiter choices. For tabular export, the Nested JSON to CSV tool uses flattened column paths and should be tested against keys that contain your chosen separators.
A safer round-trip test
Before adopting a flattening convention, create fixtures with arrays, nulls, empty containers, a key containing the delimiter, and a numeric-looking object key. Flatten, unflatten and compare the result to the original.
Reference
RFC 8259 — JSON defines JSON itself; flattening conventions are application-specific.
Flattening preserves paths; normalization redesigns structure
These operations can look similar because both reduce nested structures, but their goals differ. Flattening encodes a nested path into a key so the original hierarchy can often be reconstructed. Normalization restructures repeated entities into separate collections or tables to reduce duplication and make relationships explicit.
Flattening example
{
"user": {
"id": 7,
"profile": { "city": "Lahore" }
}
}With dot-separated paths:
{
"user.id": 7,
"user.profile.city": "Lahore"
}This is convenient for CSV exports, log fields, search indexes or key/value stores, but the delimiter becomes part of your data contract.
Normalization example
If many orders repeat the same customer object, a normalized representation might store customers by ID and let orders reference the customer ID. The objective is not a reversible path string; it is a model that represents entities and relationships cleanly.
Delimiter collisions are the main flattening trap
Suppose the original object contains a literal key named profile.city. A dot-based flattener can confuse that key with the nested path profile → city. Robust systems escape delimiters, use a structured path format, or explicitly reject ambiguous keys. Always round-trip representative production keys before choosing a convention.
Arrays need a documented convention
Some flatteners emit items.0.name; others use bracket notation such as items[0].name. Empty arrays and empty objects are especially important because a leaf-only representation can accidentally lose their existence. Decide whether preserving empty containers is required for unflattening.
When to use each approach
| Goal | Prefer | Reason |
|---|---|---|
| Export nested values into columns | Flattening | Path-like keys map naturally to columns |
| Search/log enrichment | Flattening | Simple field access |
| Remove duplicated entities | Normalization | Models relationships explicitly |
| Design relational storage | Normalization | Avoids repeated groups and update anomalies |
| Temporary inspection/debugging | Flattening | Low-friction view of nested paths |
Round-trip test before relying on unflatten
Take samples containing nested arrays, nulls, booleans, numeric-looking keys, empty containers and keys that contain your delimiter. Flatten them and unflatten them, then compare the resulting JSON structurally with the original. The JSON Flatten / Unflatten tool is useful for this inspection, but no path convention is automatically correct for every dataset.