A JSON to TOML converter turns JSON data into a TOML configuration file. Paste a JSON object and this JSON to TOML converter writes clean TOML v1.0.0, with simple values as key = value lines, nested objects as [tables] and arrays of objects as [[arrays of tables]]. Copy the result or download it as a .toml file for tools and apps that use TOML for their settings.
What TOML is
TOML, Tom's Obvious, Minimal Language, aims to be a minimal configuration file format that's easy to read because of its obvious semantics. It's designed to map unambiguously to a hash table and to be easy to parse in many languages. TOML is case-sensitive, a TOML file must be valid UTF-8, files should use the .toml extension, and the media type is application/toml. A # starts a comment, which is one reason people like TOML for hand-edited configuration.
How the JSON becomes TOML
- Strings, numbers and booleans become key = value lines.
- Nested objects become tables with a header such as [server], or [server.tls] for deeper levels.
- Arrays of objects become arrays of tables, each element under its own [[products]] header, in order.
- Other arrays become inline arrays, such as ports = [8000, 8001].
- Objects inside other arrays become inline tables, such as { x = 1, y = 2 }.
- null has no TOML equivalent, so those keys are left out, and the converter tells you how many.
Keys
Bare TOML keys may only contain ASCII letters, digits, underscores and dashes. Keys with any other characters, such as spaces, dots or accented letters, are written in quotes, as in "character encoding" = "value". The converter quotes keys only when it has to, following the specification's advice to use bare keys except when absolutely necessary.
How to use the JSON to TOML converter
- Paste your JSON object into the box.
- Press Convert to TOML.
- Check the result, including any note about null values left out.
- Copy or download the TOML file.
Example
This JSON:
{"title": "My app", "server": {"host": "localhost", "port": 8080}, "products": [{"name": "Hammer"}, {"name": "Nail"}]}
becomes title = "My app", then a [server] table with host = "localhost" and port = 8080, then two [[products]] tables with name = "Hammer" and name = "Nail".
Strings and numbers
Strings are written as TOML basic strings in double quotes, with quotes, backslashes and control characters escaped, so any text from your JSON is preserved. Whole numbers stay integers and decimals stay floats. Very large whole numbers that JavaScript can't store exactly are written as floats, so check any IDs or large counters in the result.
Is it private?
Yes. The conversion happens in your browser, and nothing is uploaded.
Where TOML is used
TOML is popular for configuration files that people edit by hand, because its sections, key = value lines and comments are easy to read. Many build tools, package managers, static site generators and applications use TOML for their settings. If you have settings in JSON, for example exported from a program or written for an API, converting to TOML gives you a file in the format those tools expect.
Tables and arrays of tables
In TOML, a table is a collection of key/value pairs under a header in square brackets, such as [server]. Nested tables use dotted headers, such as [server.tls]. An array of tables uses a header in double brackets, such as [[products]]: the first instance defines the array and its first table, and each later instance adds another table to the array, in the order they appear. The converter follows these rules, so the TOML maps back to the same structure as your JSON.
Order of keys
Within each table, the converter writes simple values first, then nested tables and arrays of tables. TOML requires this: once a table header appears, the lines that follow belong to that table, so a parent's simple values must come before any of its sub-tables. The keys keep the order they had in your JSON within each group.
Checking the result
Open the TOML file in the tool that will use it, or in a TOML validator, before relying on it. Pay attention to any keys that were left out because their value was null, and add sensible values if the tool needs those settings. Because JSON has no comments, you may want to add comments in the TOML file to explain important settings for whoever edits it next.
Going the other way
Most programming languages have libraries that read TOML into the same kind of structure JSON produces, so you can keep configuration in TOML and load it as data in your code. If you need YAML or XML instead, use our JSON to YAML or JSON to XML converters.
Common mistakes
- A top-level array. TOML needs an object at the top; wrap the array under a key.
- Relying on null. TOML can't represent it; use an empty string or leave the key out.
- Invalid JSON, such as trailing commas or single quotes.
- Expecting comments to appear; JSON has none to carry over.
What next
Use this often? Add JSON to TOML to your Home screen.
Frequently asked questions
How does the JSON to TOML converter work?
It writes each simple value as key = value, each nested object as a [table], and each array of objects as [[arrays of tables]], following TOML v1.0.0.
Why must the JSON be an object?
A TOML file is a table, so the top level must be an object with keys.
What happens to null values?
TOML has no null, so those keys are left out and the converter tells you how many.
Are special characters in keys handled?
Yes. Keys with anything other than letters, digits, underscores and dashes are quoted.
Is my JSON uploaded?
No. It's converted in your browser.
Sources
Was this tool helpful?
What went wrong?
We only receive the reason you pick, never what you typed into the tool.
Thanks for your feedback.