Flatten JSON with a Custom Delimiter
Choose dot, slash, underscore, or another delimiter so flattened JSON keys survive CSV headers, BI tools, databases, and source keys with dots.
Paste your JSON → Get results instantly (no signup)
→ Flatten or nest keys in this JSON structure and flatten nested object.
1{2 "user.name": "Alice",3 "user.address.city": "NYC",4 "user.address.zip": "10001"5}Love the result?
Use this exact pipeline in your app, backend, or LLM workflow.
No setup needed. Works with curl, Node, Python.
Uses example data. For edited input, copy from the playground.
Works with:
- Dot path keys
- Slash-separated paths
- Underscore column names
- Delimiter collision fixes
Example: input → output
Flatten JSON with a custom delimiter
The delimiter is the character between path segments in flattened JSON. Dot paths such as user.address.city are readable, but they are not always safe. Some source keys already contain dots. Some databases, CSV tools, and BI systems prefer underscores or slashes. Choosing the delimiter up front prevents broken columns and ambiguous unflattening later.
This page uses the same engine as the JSON flattener, with examples focused on dot, slash, underscore, and delimiter collision handling.
Dot vs underscore vs slash
Nested input:
{
"user": {
"address": {
"city": "Paris"
}
}
}Dot delimiter:
{ "user.address.city": "Paris" }Underscore delimiter:
{ "user_address_city": "Paris" }Slash delimiter:
{ "user/address/city": "Paris" }The values are the same. The destination determines which key style is safest.
Which delimiter should you use?
Use dots for human-readable path maps, diffs, logs, and examples. Use underscores when the result becomes CSV headers for tools that dislike dots. Use slashes when you want path-like keys that resemble URLs or JSON Pointer-style navigation.
If the original JSON keys already contain dots, do not use dot output unless your workflow has escaping rules. Use underscores, slashes, or another separator instead.
Why flattening breaks CSV sometimes
Flattening itself does not break CSV, but delimiter and array choices can. A dotted key may be treated specially by some tools. An expanded array can produce too many columns. A delimiter collision can make user.name ambiguous: is it a nested path, or was user.name an original key?
For spreadsheet exports, use Flatten JSON for CSV and choose a delimiter your destination preserves.
Delimiters and unflattening
Unflattening only works cleanly when the delimiter is known and unambiguous. If you flatten with _, you need to unflatten with _. If source keys contain the delimiter, the reverse operation may rebuild the wrong shape.
Use Unflatten JSON to test whether your chosen delimiter round-trips before using it in an import workflow.
Related flatten JSON tools
- JSON flattener - flatten nested JSON with configurable path keys.
- Flatten JSON for CSV - choose column-safe separators.
- Flatten JSON in Python - compare delimiter behavior with backend code.
- Flatten JSON in Node.js - choose path keys for server-side scripts.
Frequently asked questions
What delimiter should I use when flattening JSON?+−
Dots are readable, underscores are often safer for CSV headers, and slashes work well for path-like keys. Choose the separator your destination preserves.
What is a delimiter collision?+−
A delimiter collision happens when an original key already contains the separator. For example, a source key named user.name becomes ambiguous when dot paths are used.
Can I unflatten JSON with a custom delimiter?+−
Yes, as long as you use the same delimiter and the flat keys are unambiguous.
Related tools
- Rename KeysRename known keys or convert key casing without changing the underlying values
- Find & ReplaceFind and replace matching keys or values across JSON using broad search patterns
- FilterFilter rows, items, keys, or values by explicit conditions and keep only the matches you want
- Pick FieldsKeep only a known allowlist of fields and remove everything else
- RestructureFlexibly restructure collections by grouping, unwinding, transposing, or rearranging nested data
Read more on the blog
Advanced usage (optional)
Flatten / Nest
v1.0.0Description
Flatten / Nest
Convert between nested and flat object structures. Flatten deep objects into single-level key-value pairs, or nest flat keys back into hierarchical objects. Supports multiple key formats: delimiter-separated, camelCase, snake_case, PascalCase, and kebab-case.
Modes
Flatten
Convert nested objects into flat keys. Each nested path becomes part of the key name.
{ "user": { "name": "Alice" } } → { "user.name": "Alice" }Nest
Convert flat keys back into nested objects by splitting on the delimiter or case boundaries.
{ "user.name": "Alice" } → { "user": { "name": "Alice" } }Key Formats
Delimiter (default)
Join/split key segments with a character (default: .).
- Flatten:
user+name→user.name - Nest:
user.name→user/name
camelCase
Join/split on uppercase letter boundaries.
- Flatten:
user+address+city→userAddressCity - Nest:
userAddressCity→user/address/city
snake_case
Join/split on underscores.
- Flatten:
user+address+city→user_address_city - Nest:
user_address_city→user/address/city
PascalCase
Same as camelCase but with uppercase first letter.
- Flatten:
user+name→UserName
kebab-case
Join/split on hyphens.
- Flatten:
user+name→user-name
Configuration
| Field | Type | Default | Description |
|---|---|---|---|
| Mode | enum | flatten | flatten or nest |
| Key Format | enum | delimiter | delimiter, camelCase, snake_case, PascalCase, or kebab-case |
| Delimiter | string | . | Character(s) used to join/split key segments (only for delimiter format) |
| Max Depth | number | 0 | Maximum nesting depth to flatten (0 = unlimited) |
| Target Paths | path-picker | [] | Scope operation to specific paths only (empty = apply everywhere) |
Use Cases
API Integration
- Flatten for forms: Convert nested API responses to flat form field names
- Nest for APIs: Convert flat form data back to nested API request bodies
- Format conversion: Transform between dot-notation and camelCase conventions
Database Operations
- MongoDB flattening: Flatten nested documents for tabular export
- SQL mapping: Convert hierarchical JSON to flat column names for SQL insertion
- Schema migration: Convert between naming conventions (snake_case ↔ camelCase)
Configuration Management
- Environment variables: Flatten config objects to dot-notation for
.envfiles - Depth limiting: Flatten only the first level while preserving deep structures
Configuration
| Name | Type | Default | Description |
|---|---|---|---|
| Mode | enum | flatten | flatten: convert nested objects to flat keys. nest: convert flat keys back to nested objects. flatten nest |
| Key Format | enum | delimiter | delimiter: use a character to join/split. Others: camelCase, snake_case, PascalCase, kebab-case. delimiter camelCase snake_case PascalCase kebab-case |
| Delimiter | string | . | Character(s) used to join/split key segments (default is dot) |
| Max Depth | number | 0 | Maximum nesting depth to flatten (0 = unlimited) |
| Target Paths | path-picker | [] | Scope operation to specific paths only (empty = apply everywhere) |
Examples
Flatten or nest keys in this JSON structure and flatten nested object.1{2 "user.name": "Alice",3 "user.address.city": "NYC",4 "user.address.zip": "10001"5}API Usage
curl -X POST https://your-domain.com/api/v1/utilities/structure.flatten-nest \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs":{"primary":{"user":{"name":"Alice","address":{"city":"NYC","zip":"10001"}}}},"config":{"mode":"flatten","delimiter":".","maxDepth":0,"targetPaths":[]}}'1{2 "user.name": "Alice",3 "user.address.city": "NYC",4 "user.address.zip": "10001"5}