What is a JSON Flattener?
A JSON Flattener converts a nested JSON object into a single-level structure. Nesting that was expressed by objects inside objects is rewritten as key paths: the property names that lead to a value are joined together with a delimiter, and the value itself sits directly under that one key. An address object holding a city stops being an object and becomes the key address.city.
Nothing is renamed and no value changes type. The nesting hierarchy is still there — it has simply moved out of the structure and into the key names, so a reader can tell exactly where any value came from. That is what makes a flattened object useful: it is one level deep, so every field can be addressed, stored or compared on its own.
Developers reach for this whenever the system on the other end cannot cope with depth. Spreadsheets hold one value per cell. Database columns and search indexes expect one field per row. A flat key/value config file has no concept of a sub-object at all. Flattening is the transformation that gets a nested document into a shape those systems accept, without rewriting the data by hand.
How to flatten JSON online
The workflow is four steps: paste, choose your options, flatten, copy.
- Paste your nested JSON into the 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.
- Choose a delimiter and decide how arrays should be handled. Dot notation is the default; Add array indexes to keys is the setting to use when an array has to become individual fields.
- Click Flatten JSON. Every leaf value is written into one flat object, and the result panel reports how many keys were produced and how deep the document was. Ctrl+Enter does the same thing from the keyboard.
- Read the Flattened JSON panel and press Copy to take the result, or Download to save it as flattened.json.
Everything runs locally in your browser, so there is nothing to install, no account to create and no data to upload.
JSON flattening example
The same document appears below as nested JSON and as the flat object this flattener produces. Two properties are already at the top level, so they keep their own names. The two properties inside profile each gain the name of the object they came from, which is what records where they belonged.
{
"name": "John",
"profile": {
"age": 30,
"city": "Lahore"
}
}{
"name": "John",
"profile.age": 30,
"profile.city": "Lahore"
}Read the result as a sentence about the original: profile.age is the age that lived inside the 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" — flattening moves the hierarchy, it does not rewrite the values.
How arrays are handled when flattening
Arrays are the one part of JSON with no equivalent in a flat key/value object, because there is no way to store a list under a single key without storing it as JSON again. This flattener offers both workable answers and lets you choose, because the right one depends on what you are feeding the result into.
Keep arrays as JSON
The array stays a single value under its own key and nothing inside it is flattened. This is the right choice when the list itself is the value you care about — a list of tags, a list of permissions — because it keeps the array intact and in order, and it does not multiply your field count.
{
"user": {
"name": "John",
"skills": ["JavaScript", "Python", "React"]
}
}{
"user.name": "John",
"user.skills": [
"JavaScript",
"Python",
"React"
]
}Add array indexes to keys
Every array item is written into its own key and its position becomes part of the path. This is the mode you want when each item has to become an individual field, for example to load it into columns. An item that is itself an object is flattened the same way, so a list of users produces one key per field per user.
{
"user": {
"name": "John",
"skills": ["JavaScript", "Python", "React"]
}
}{
"user.name": "John",
"user.skills.0": "JavaScript",
"user.skills.1": "Python",
"user.skills.2": "React"
}An array of objects
The same two modes applied to a list of objects. Preserving keeps the list as one nested value; indexing writes one key per property per user, and the number in the path tells you which user it belongs to.
{
"users": [
{ "name": "John", "role": "Developer" },
{ "name": "Sarah", "role": "Designer" }
]
}{
"users.0.name": "John",
"users.0.role": "Developer",
"users.1.name": "Sarah",
"users.1.role": "Designer"
}Keeping the same document in both modes is worth noticing: 12 output lines with the array kept whole, against 6 with every index expanded. That difference in field count is exactly the trade-off you are choosing between. When a single table is becoming hard to read, splitting the parent record from the child records is usually better than letting one flattened object absorb everything.
The delimiter, or key separator
The delimiter is the character placed between the key names that make up a path. Dot notation is the default because it is the convention almost everything else uses — MongoDB, Elasticsearch, Laravel, JSONPath and jq all read address.city the same way.
{
"user": {
"name": "John"
}
}{
"user.name": "John"
}Switch the delimiter to an underscore and the same input is written with a key that is safe in places a dot is not — environment variable names, some spreadsheet column names, or a system that treats a dot as a nesting character in its own right.
{
"user": {
"name": "John"
}
}{
"user_name": "John"
}Pick the delimiter your target system expects rather than the one that looks nicest. One caveat is worth knowing: if a property name already contains the delimiter, for example a literal "a.b" key, two different paths can produce the same flat key. The flattener detects that and says so rather than letting one value quietly overwrite the other.
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 | Nested JSON | Flat JSON |
|---|---|---|
| Where the hierarchy lives | In the structure, as objects inside objects | In the key names, as a combined path |
| Reading one deep value | Walk each object above it first | Look it up by its full key directly |
| Fits a spreadsheet column or SQL field | Awkward — needs expanding | Direct fit |
| Key rename in a deep branch | Change it once, every reader sees it | Every affected key path has to change with it |
| Natural for | A document you read, send and pass along | A row, a field list, a config map or an index |
A practical way to decide: if a program reads the data, pick whichever structure that program expects and flatten only at the boundary. Nesting is usually the better shape for an API response because it stays compact and mirrors the problem domain; flat is usually the better shape for storage and analysis because there is one field per row. Neither is a general improvement on the other — they are two representations of the same data.
When is JSON flattening useful?
Flattening is worth doing when something downstream cannot handle nesting. These are the situations that come up most often.
Working with tabular data
A spreadsheet cell holds one value, not a sub-table. Flattening turns every nested property into its own column name, so address.city becomes a column you can actually write a row into.
Loading into a database or search index
Document stores, key/value tables and search engines all map a row or a document to a set of flat fields. A flattened key path can be used directly as a field name.
Simplifying access to nested values
Reading one value out of a deep structure means walking the chain above it. A flat object lets you address the value directly by its key path, which is simpler in a query, a script or a config lookup.
Transforming API responses
An API built for an application returns structure that is awkward for a dashboard or an analytics tool. Flattening is a quick way to reshape the response before it goes anywhere else.
Debugging and inspecting deeply nested data
When something in a payload is not what you expected, a flat list of key paths makes the whole document scannable in one screen, which nesting is not.
Feeding tools that expect key/value pairs
Configuration systems, environment variable files, form libraries and many queue and metrics tools all read flat key/value data rather than a nested document.
Flattening is also an intermediate step rather than an end in itself: a flat key/value object is easy to map, transform or load into another system. Just be aware of the two limits worth checking before you commit to it — an empty object has no leaf value and so cannot appear in the output, and expanding an array into indexed keys can multiply your field count. If you are flattening the same API response regularly, it is worth keeping the raw payload as well so nothing is lost if the shape of that response changes.
How this flattener works
The same rules apply every time you flatten a document, whichever delimiter and array mode you choose. 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 |
|---|---|
| Nested objects become key paths | Every level of property names is joined into one key, so profile.address.city is a single flat key holding the city. |
| 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 out. |
| Key order follows the document | The flattened object is written in the same sequence as the input, so the output reads in the order the original did. |
| Arrays are your choice | An array either stays one value under its own key, or every item is written into its own key with its index in the path. You pick, and the page shows both. |
| Empty objects are reported, empty arrays are kept | An empty object has no properties, so it has no value to write and the path cannot appear in a flat object; the tool names each one it leaves out. An empty array is a value like any other, so it is kept as-is unless you ask for array indexes, which is the one setting that has nowhere to put it. |
| Invalid JSON is rejected | The document has to parse before anything is flattened. A syntax error is reported with its line and column, no result is produced and your input is left untouched. |
Related JSON tools
Flattening is one step in a JSON workflow. These are the other Calzyra tools you are most likely to reach for next.
- Need to turn flat keys back into the original nested structure?JSON Unflattener
- Need to confirm a document is valid JSON and find the exact syntax error?JSON Validator – Validate JSON Online
- Need to re-indent your flattened result so it is comfortable to read?JSON Formatter
- Need to compare two flattened payloads field by field?JSON Diff Tool
- Need to see the nesting itself as collapsible nodes?JSON Tree Viewer
- Need the flattened 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 Flattener?
A JSON Flattener converts a nested JSON object into a single-level object where every value sits under one key. Instead of an object inside an object inside an object, the nesting is written into the key: address.city rather than an address object holding a city. Nothing is renamed and no value changes type - the hierarchy simply moves from the structure into the key names.
How do I flatten JSON?
Paste your nested JSON into the JSON Input panel, press Flatten JSON, and read the result in the Flattened JSON panel. Press Copy to put it on your clipboard. Ctrl+Enter flattens without leaving the keyboard. You can also change the delimiter and the array mode first, and the result panel always shows the key count and the depth it found.
How do I flatten nested JSON?
The flattener walks the document for you and joins every level of property names it passes through. A document nested five levels deep becomes an object whose every key is one level deep, in the same order as the original. There is no depth limit to work around for real payloads, and the result reports the depth it walked.
Can I flatten JSON online?
Yes, and nothing is uploaded. The document is parsed and flattened 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 Flattener 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.
Can nested JSON objects be flattened?
Yes, and nesting is the normal case rather than an edge case. Every object property becomes part of the key path, so profile.address.city is written as a single key. An empty object is the one thing that cannot be represented: it has no properties, so it has no leaf to write and the tool tells you which paths were left out instead of losing them silently.
How are JSON arrays handled when flattening?
It is your choice, because a flat key/value object has no way to hold a list. Keep arrays as JSON keeps the whole array under its own key and does not touch what is inside it. Add array indexes to keys writes each item into its own key with its position in the path, so a users array of objects becomes users.0.name, users.0.role, users.1.name and so on. Both modes are shown side by side on this page so you can pick the one your target expects.
What is the difference between flat JSON and nested JSON?
Nested JSON groups related properties inside objects, which is compact and mirrors the structure of the problem. Flat JSON keeps every value at one level and records the relationship in the key name. Neither is universally better: nesting is natural for a document you read and pass along, while a flat structure is far easier to load into a spreadsheet column, a database row, a search index or a simple map.
Why would I flatten a JSON object?
Most often because the system on the other end cannot handle nesting. Spreadsheets, SQL columns, document stores and search indexes all want one field per row. Flattening also makes a deeply nested payload much easier to inspect, because each value can be read straight off its key without following the chain of objects above it.
What happens if my JSON is invalid?
Nothing is flattened and no result is produced, so a broken document can never be mistaken for a flattened 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 flattening lose information?
For nested objects, no. The keys still describe the whole path to the value, so nothing is lost. Two things are worth knowing: an empty object has no leaf value and so is left out, while an empty array is kept as a value unless you choose array indexes, which have no items to write; and if a property name already contains your delimiter, for example a literal "a.b" key, two different paths can produce the same flat key. The tool reports each case rather than passing it off as a clean result.