Flatten JSON for Testing
Turn nested API responses into stable path maps for fixtures, snapshot reviews, contract assertions, and easier test failure messages.
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:
- Test fixtures
- Snapshot reviews
- Contract assertions
- Mock API responses
Example: input → output
Flatten JSON for testing
Nested API responses make tests harder to read when every assertion has to reach through several objects. Flattening JSON creates stable path keys such as user.profile.email and invoice.total, which can make fixtures, snapshots, contract checks, and failure messages easier to inspect.
This page uses the same engine as the JSON flattener, with examples focused on testing workflows.
Test fixture example
Nested response:
{
"user": {
"id": "u_1",
"profile": {
"email": "ada@example.com",
"plan": "team"
}
},
"flags": {
"beta": true
}
}Flattened fixture:
{
"user.id": "u_1",
"user.profile.email": "ada@example.com",
"user.profile.plan": "team",
"flags.beta": true
}That flat shape is useful when a test only cares about specific leaf values and you want failure output to show exact paths.
When flattening helps tests
- Snapshot review for deeply nested API responses.
- Contract assertions where missing paths should be obvious.
- Mock payload comparison across versions.
- Fixture generation from real API samples.
- Debug output for CI failures.
For Node-specific testing examples, use Flatten JSON in Node.js. For language-neutral API samples, use Flatten JSON API Example.
When not to flatten for tests
Do not replace every nested fixture with a flat one. If the code under test consumes nested JSON, keep nested fixtures too. Flattened JSON is best as an inspection layer, an assertion map, or a secondary snapshot that makes leaf-level changes visible.
If arrays are important to the behavior, be careful with indexed paths. A changed array order can make many path keys change even when the semantic result is acceptable.
Common testing mistakes
- Testing only flattened output when production code consumes nested JSON.
- Snapshotting unstable array indexes.
- Losing type information by stringifying values before assertions.
- Using different delimiters across test helpers and fixtures.
- Forgetting to unflatten when a mock API expects nested response bodies.
Related flatten JSON tools
- JSON flattener - general flatten and unflatten workflow.
- Flatten JSON API Example - realistic nested response example.
- Flatten JSON in JavaScript - frontend helper behavior.
- Unflatten JSON - rebuild nested mocks from flat keys.
Frequently asked questions
Why flatten JSON for tests?+−
Flattening nested responses into path keys can make assertions, snapshots, fixtures, and failure messages easier to read.
Should test fixtures be flat or nested?+−
Keep nested fixtures when production code consumes nested JSON. Use flat fixtures as an inspection or assertion layer.
Does flattening help contract tests?+−
Yes. Flat paths make missing fields and changed leaf values easier to spot in contract checks.
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}