How to use the json flatten unflatten tool
- Choose Flatten nested JSON or Unflatten to nested JSON.
- Paste your JSON. Set the key separator (a dot by default) and how array positions are written.
- Decide whether to keep empty objects and lists when flattening.
- Copy or download the result, or use Use result as input to go back the other way.
A nested object and its flat form
The JSON {"a": {"b": 1}} flattens to {"a.b": 1}. A list inside, such as {"user": {"langs": ["en", "fr"]}}, flattens to {"user.langs.0": "en", "user.langs.1": "fr"}, or user.langs[0] and user.langs[1] in bracket style.
Unflattening reverses it. The keys user.langs.0 and user.langs.1 become a list because the positions are 0 and 1 with no gaps. If the positions were 1 and 3, the level would stay an object with the keys "1" and "3".
Why flatten JSON
Flat keys are handy for spreadsheets and CSV files, for search indexes, for environment style settings, for comparing two documents line by line and for tools that accept only one level of keys. Rebuilding nested JSON from flat keys is the common way to read such data back.
The path to every value is the key. A value inside an object adds its name, and a value inside a list adds its position, counted from 0. Empty objects and lists have no values inside, so they are either kept as empty values or dropped, as you choose.
Collisions and limits
If a real key already contains the separator, for example the key "a.b", flattening cannot tell it apart from the path a then b. When two different paths would produce the same key, the tool stops with an error naming the key, and you can pick another separator. Unflattening reports a conflict when one key holds a value and another goes deeper through it, such as a and a.b.
Keys named __proto__ or constructor are treated as ordinary text and cannot change how objects behave. Input is limited to 1,000,000 characters, 100,000 keys and 100 levels, and numbers are read as ordinary JavaScript numbers. Nothing is uploaded. See also the JSON formatter and validator, the JSON viewer, the JSONPath tester and the query string to JSON converter.
Assumptions and limits
- Array positions count from 0 and are written with the separator or in brackets.
- Unflattening makes a list only for whole number keys 0, 1, 2 and so on with no gaps.
- Keys that already contain the separator can cause a collision error when flattening.
- Numbers beyond 15 digits can lose precision, because JSON is read with JavaScript numbers.
Frequently asked questions
How do I flatten nested JSON?
Paste it, choose Flatten and pick a separator. Each value gets a key made from the names and positions on the path to it, such as a.b.c.
Can I flatten with underscores instead of dots?
Yes. Change the key separator to an underscore and the keys become a_b_c. Use the same separator when you unflatten.
What happens to empty lists?
With the keep option on, they stay as empty values. With it off they are left out of the flat result.
Why did unflattening make an object instead of a list?
Lists are rebuilt only when the positions are 0, 1, 2 and so on with no gaps. Other numeric keys are kept as ordinary keys of an object.