What is a JSON Unflattener?
A JSON Unflattener converts a flat JSON object back into a nested one. In a flat document, the nesting is stored in the key names rather than in the structure: the property names that lead to a value are written out in one key, separated by dots, with the value sitting at the end of it. An address object holding a city stops being an object and becomes the single key address.city.
Unflattening is the move in the other direction. Every key is split at its dots, an object is created for each segment the path passes through, and the value is written at the end of the chain. The hierarchy moves out of the key names and back into the structure, where a reader can follow it by looking at the document instead of decoding the property names.
Nothing is renamed and no value changes type along the way. A number stays a number, a boolean stays a boolean and null stays null, so the restored document is exactly as machine-readable as the flat one it came from. That is the whole point: the two are the same data written in two shapes, and this tool moves between them.
How to unflatten JSON online
The workflow is four steps: paste, check the paths, unflatten, copy.
- Paste your flat JSON into the Flat JSON Input panel. Use Load example if you just want to see how it works first, or Upload .json to read a file from your machine.
- Check that the keys are separated by dots, which is what the tool splits on. A key such as profile.city is a path; a key without a dot is a top-level property and is left as it is.
- Click Unflatten JSON. Every key path is split into segments and an object is created for each one, and the result panel reports how many paths were rebuilt and how deep the result goes. Ctrl+Enter does the same thing from the keyboard.
- Read the Nested JSON Output panel and press Copy to take the result, or Download to save it as unflattened.json.
Everything runs locally in your browser, so there is nothing to install, no account to create and no data to upload.
JSON unflattening example
The same document appears below as the flat object this tool receives and as the nested object it produces. Two properties are already at the top level, so they keep their own names. The two properties whose keys carry a path each gain the object their segment names describe.
{
"name": "John",
"profile.age": 30,
"profile.city": "Lahore"
}{
"name": "John",
"profile": {
"age": 30,
"city": "Lahore"
}
}Read the result as a sentence about the input: profile.age was the age living inside a profile object, and profile.city is the city from that same object. The age is still the number 30 and the city is still the string "Lahore" — unflattening rebuilds the hierarchy, it does not rewrite the values.
{
"user.name": "John",
"user.address.city": "Lahore",
"user.address.country": "Pakistan"
}{
"user": {
"name": "John",
"address": {
"city": "Lahore",
"country": "Pakistan"
}
}
}Three levels of path build two objects in between, and both keys that start with user. end up sharing the same user object. That sharing is what makes the result a single document rather than one subtree per key.
How numeric path keys are restored
A flat key cannot tell you that a segment was an array index rather than a property name that happens to be a number. This tool does not guess: numeric segments are restored as object properties, and the result panel tells you how many it found so the shape is never a surprise.
{
"user.name": "John",
"user.skills.0": "JavaScript",
"user.skills.1": "Python",
"user.skills.2": "React"
}{
"user": {
"name": "John",
"skills": {
"0": "JavaScript",
"1": "Python",
"2": "React"
}
}
}The skills value came back as an object whose properties are named "0", "1" and "2". An array that was kept as a JSON value in the first place — the JSON Flattener's default — has no key path to split and passes through untouched, so use that mode when you need the list to stay a list.
Value types survive the round trip
Unflattening only rearranges where values sit. Nothing is stringified, no number is parsed as text and no boolean is turned into the words true or false.
{
"active": true,
"verified": false,
"score": 99.5,
"note": null,
"user.name": "John"
}{
"active": true,
"verified": false,
"score": 99.5,
"note": null,
"user": {
"name": "John"
}
}Flat JSON vs nested JSON
These are two ways of writing the same data, and the difference is entirely about where the hierarchy is stored. Neither is universally better — which one you want depends on what reads the result next.
{
"user.profile.name": "John"
}{
"user": {
"profile": {
"name": "John"
}
}
}| Aspect | Flat JSON | Nested JSON |
|---|---|---|
| Where the hierarchy lives | In the key names, as a combined path | In the structure, as objects inside objects |
| Reading one deep value | Look it up by its full key directly | Walk each object above it first |
| Fits a spreadsheet column or SQL field | Direct fit | Awkward — needs expanding |
| Reading it as a document | Every path has to be decoded by eye | The structure shows the relationship |
| Natural for | A row, a field list, a config map or an index | A document you read, send and pass along |
A practical way to decide: if a program reads the data, pick whichever structure that program expects and move at the boundary. Flat is usually the better shape for storage and analysis because there is one field per row; nesting is usually the better shape for an API response because it stays compact and mirrors the problem domain. Neither is a general improvement on the other — they are two representations of the same data.
When is JSON unflattening useful?
Unflattening is worth doing when the shape you have is not the shape the next step expects. These are the situations that come up most often.
Feeding a nested API from flat sources
An environment file, a key/value store or a form library hands you flat keys. Most application code expects an object tree, so the paths have to be expanded before anything reads them.
Coming back from a spreadsheet export
Columns written from a flattened document come back with the path still inside the name. Rebuilding the objects turns those columns into the document the application started with.
Undoing a flatten you did for inspection
Flattening is a good way to read a deeply nested payload in one screen. Once you have found what you were looking for, unflattening puts the document back into the shape the rest of the pipeline expects.
Rebuilding a configuration document
Config systems that accept dotted keys - Spring, Laravel, systemd, many queue and metrics tools - produce a flat map that a program reading a nested config cannot use directly.
Preparing data for a document store
A key/value table maps cleanly to flat fields, but a document database wants real nesting. Unflattening is the step that makes a row set insertable as a document.
Verifying a flatten round trip
Restoring a flattened payload and comparing it with the original is the quickest way to confirm that nothing was lost along the way - which is exactly what this page lets you do by eye.
It is also the second half of a round trip rather than an end in itself: flatten to inspect, load or transport, then unflatten to get back to the document the application started with. Worth checking before you rely on it — a property name that already contains a dot cannot be told apart from the nesting it imitates, so keep the original payload alongside a flattened copy if the distinction matters.
How this unflattener works
The same rules apply every time you restore a document. They are listed here exactly as the tool applies them, including the two cases that are easy to be surprised by.
| Rule | What the tool does |
|---|---|
| Keys are split on the dot | Each key is divided at every dot, and an object is created for each segment passed through. A key without a dot is a top-level property and is written as it is. |
| Value types are never changed | A string stays a string, a number stays a number, true stays a boolean and null stays null. Nothing is coerced into a string on the way in. |
| Objects are merged, not replaced | If a path runs through an object an earlier key already built, it is reused, so {"user.name": "John"} and {"user.age": 30} combine into one user object. |
| Numeric segments become object properties | skills.0 restores as an object with a property named "0", not as an array. A flat key records that the segment is a number; it does not record that the original value was a list, so guessing would change the data. The result panel reports how many of these it found. |
| Overlapping keys are reported | Two keys can describe the same position - {"a": 1, "a.b": 2} says a is a number and an object at once. The later key wins and the tool names the value it replaced, rather than dropping one quietly. |
| Invalid JSON is rejected | The document has to parse before anything is rebuilt. A syntax error is reported with its line and column, no result is produced and your input is left untouched. |
Related JSON tools
Restoring a document is one step in a JSON workflow. These are the other Calzyra tools you are most likely to reach for next.
- Need to turn a nested document back into flat key paths?JSON Flattener
- Need to confirm a document is valid JSON and find the exact syntax error?JSON Validator – Validate JSON Online
- Need to re-indent your restored result so it is comfortable to read?JSON Formatter
- Need to see the restored nesting itself as collapsible nodes?JSON Tree Viewer
- Need to compare the restored payload with another version field by field?JSON Diff Tool
- Need the restored fields as rows and columns for a spreadsheet?JSON to CSV Converter
- Need YAML output instead?JSON to YAML Converter
- Need an XML document instead?JSON to XML Converter
- Need to strip whitespace back out before sending it anywhere?JSON Minifier – Minify JSON Online
Frequently Asked Questions
What is a JSON Unflattener?
A JSON Unflattener restores a flat JSON object back into a nested one. Where a flattener joins the property names that lead to a value into a single key such as profile.city, the unflattener splits that key apart again and rebuilds the objects between the segments. Nothing is renamed and no value changes type - the hierarchy moves out of the key names and back into the structure.
How do I unflatten JSON?
Paste your flat JSON into the Flat JSON Input panel, press Unflatten JSON, and read the result in the Nested JSON Output panel. Press Copy to put it on your clipboard. Ctrl+Enter does the same thing without leaving the keyboard. Use Load example to see it work first, or Upload .json to read a file from your machine.
What is a key path?
A key path is a flat key that records the route to a value. In "user.address.city": "Lahore", the key says that the city lives in an address, which lives in a user. The dots are the separators between the property names, and splitting on them is what tells the tool where each new object starts and where the value goes.
How does the delimiter affect JSON unflattening?
The dot is the separator this tool splits on, because it is the convention the JSON Flattener, jq, MongoDB, Elasticsearch and JSONPath all write. A key that uses a different separator - an underscore, a slash - contains no dot, so it is left as a single property name rather than guessed at: a flat key alone does not record which character was used. If you plan to restore the result here, flatten with the dot delimiter, which is the default.
How are JSON arrays handled when unflattening?
Two cases. An array that was kept as a JSON value - the flattener's default - has no key path to split, so it passes straight through untouched, order and items included. An array that was expanded into indexed keys such as skills.0 restores as an object whose properties are named "0", "1" and so on, because a flat key records only that the segment is a number, not that it came from a list. This tool reports how many numeric path keys it found rather than turning them into arrays it cannot be sure about.
Can I unflatten JSON online?
Yes, and nothing is uploaded. The document is parsed and rebuilt inside your browser, so there is no account, no usage limit and no upload size limit. A customer record or an internal API response never leaves your machine.
Is this JSON Unflattener free?
Yes - free to use, with no sign-up, no watermark and no limits. Because the work happens locally, there is nothing to pay for and nothing throttled.
What is the difference between flat JSON and nested JSON?
They are two ways of writing the same data. Flat JSON keeps every value at one level and records the relationship in the key name, which is what a spreadsheet column, a database row or a config map wants. Nested JSON groups related properties inside objects, which stays compact and mirrors the shape of the problem. Unflattening is simply the move from the first shape to the second.
When would I need to unflatten JSON?
Most often because the shape you received is not the shape you need. A flat payload coming from a spreadsheet import, an environment file or a key/value store has to become a nested document before an application can read it. It is also the way back after you have flattened a payload to inspect it, load it into columns or send it through a system that cannot handle depth.
What happens if my JSON is invalid?
Nothing is rebuilt and no result is produced, so a broken document can never be mistaken for a restored one. The tool reports the first syntax error with its line, column and the offending line of text, and your input is left exactly as you typed it so you can fix it in place. The JSON Validator is the place to go if you want to check syntax on its own.
Does unflattening lose information?
For ordinary key paths, no: the nesting that was written into the keys is written back into the structure, and value types are untouched. Three cases are worth knowing. A property name that contains a dot cannot be told apart from the nesting it imitates, so two paths can describe the same position - the later key wins and the tool says so. Numeric segments restore as object properties rather than arrays. A document that is not a flat object has no key paths to split and is returned unchanged.