How to use the json to toml converter
- Paste or type your JSON into the text area above.
- The tool parses the input and converts it to TOML automatically as you type.
- Review the output for nested tables (shown as
[section]) and arrays of tables ([[section]]). - Copy the resulting TOML text to use in your configuration files.
How JSON maps to TOML
TOML (Tom's Obvious Minimal Language) uses a different structure than JSON, so the conversion follows specific rules. Top-level keys become simple key = value pairs. Nested JSON objects are converted into TOML tables denoted by square brackets like [database]. When a JSON array contains only objects, it becomes an array of tables using double brackets like [[servers]].
For example, the JSON {"server": {"host": "localhost", "port": 8080}} translates to a [server] heading followed by host = "localhost" and port = 8080 on separate lines. The converter processes keys in sorted order to ensure deterministic output every time you convert json to toml.
Type conversions reference
JSON has fewer data types than TOML, so some mapping decisions must be made during conversion. Here is how each JSON type is handled:
| JSON Type | TOML Representation | Example |
|---|---|---|
| String | Basic string (double quotes) | "hello" |
| Number (integer) | Integer | 42 |
| Number (float) | Float | 3.14 |
| Boolean | Boolean | true or false |
| Null | String "null" | "null" |
| Array (primitives) | Inline array | [1, 2, 3] |
| Array (objects) | Array of tables | [[items]] |
| Object | Table | [section] |
Note that TOML does not have a native null type. Null values from JSON are serialized as the literal string "null" so no data is lost during the round trip.
Handling edge cases
Not every valid JSON document maps cleanly to TOML. The root element in TOML must be a table (an object), so passing a bare JSON array or a primitive string will produce an error. Arrays that mix types are kept as they are, because TOML 1.0 allows mixed-type arrays, and objects inside an array that also holds other values are written as inline tables such as { a = 1 }.
Unicode characters are preserved exactly. A JSON string containing "\u00e9" will appear as the literal character e with an acute accent in the TOML output, since TOML natively supports UTF-8. Keys containing dots or special characters are automatically wrapped in double quotes to comply with the TOML specification.
When to use TOML over JSON
TOML is designed primarily for configuration files where human readability and comments matter. While JSON is ubiquitous for API payloads and data interchange, TOML offers a cleaner syntax for settings files because it avoids excessive braces and quoting. Many modern tools like Rust's Cargo, Python's Poetry and Go's module system prefer TOML for their manifest files.
If you need to transform configuration data between formats, this json to toml converter handles the structural differences automatically. For other data transformations, you might also explore tools like json to xml or YAML to JSON depending on your target ecosystem.
Deterministic key ordering
When converting json to toml, the order of keys can affect readability and version control diffs. This converter sorts all object keys alphabetically before emitting them. Simple key-value pairs are always written first within a table, followed by any nested sub-tables. This ensures that running the same JSON through the converter multiple times produces identical TOML output.
For instance, given {"z": 1, "a": 2, "m": {"x": 3}}, the output will list a first, then z, and finally the [m] table block. This predictable ordering makes it easier to review changes in source control when configuration files are updated programmatically.
Worked examples
| Example | Input | Result |
|---|---|---|
| Simple object | JSON input: {"name":"my-app","version":2,"debug":true} | debug = true / name = "my-app" / version = 2 |
| Nested table | JSON input: {"database":{"host":"localhost","port":5432}} | [database] / host = "localhost" / port = 5432 |
| Array of tables | JSON input: {"servers":[{"name":"alpha","ip":"10.0.0.1"},{"name":"beta","ip":"10.0.0.2"}]} | [[servers]] / ip = "10.0.0.1" / name = "alpha" / [[servers]] / ip = "10.0.0.2" / name = "beta" |
| Mixed types | JSON input: {"title":"Config","tags":["web","api"],"meta":null} | meta = "null" / tags = ["web", "api"] / title = "Config" |
FAQ
Does this json to toml converter upload my data?
No. The parsing and conversion happen entirely inside your browser using JavaScript. Your JSON is never sent to any server.
How are JSON null values handled in TOML?
TOML does not have a null type. This converter serializes JSON null values as the string literal "null" so the information is preserved without breaking TOML syntax.
Can I convert a JSON array directly to TOML?
No. TOML requires the root element to be a table (object). If your JSON is a top-level array, wrap it in an object first, such as {"items": [...]}.
Are unicode characters preserved?
Yes. Both JSON and TOML support UTF-8 encoding. Unicode escape sequences in JSON are decoded and written as their actual characters in the TOML output.
Why are my keys in a different order than the original JSON?
The converter sorts keys alphabetically to produce deterministic output. This means converting the same JSON twice will always yield identical TOML, which is helpful for version control.
What happens if my JSON array has mixed types?
TOML 1.0 allows arrays with mixed types, so values are written as they are. Objects inside such an array become inline tables such as { a = 1 }.