Online JSON to TOML Converter

When Should You Convert JSON to TOML?

You have a JSON configuration file (like an API response), but you want to change it to TOML format because TOML is more readable, supports comments, and is better suited for long-term maintenance. For example, you might receive user settings from a backend interface and need to save them to a single configuration file on the server, or you might be working on a Rust or Python project where the configuration management libraries prefer TOML. Our online converter helps you complete this conversion with one click, saving you from manually reformatting line by line.

What is the Difference Between JSON and TOML?

JSON (JavaScript Object Notation) is a lightweight data-interchange format where all key-value pairs must be wrapped in double quotes. It is structurally compact but does not natively support comments. TOML (Tom's Obvious Minimal Language) is a format designed specifically for configuration files. It uses tables and arrays of tables to express hierarchy, supports # comments, allows unquoted keys, and is much friendlier for human reading and writing. Simply put: JSON is ideal for machine-to-machine transmission, while TOML is perfect for human editing.

Complete Example: Converting User Information from JSON to TOML

Let's assume we have a user information JSON: {"name": "John Doe", "age": 30, "active": true}. Open our converter and paste this content into the JSON input box on the left (note that the lack of outer square brackets indicates an object). Click the "Convert" button, and the output box on the right will display:

name = "John Doe"
age = 30
active = true

Each line of the converted TOML corresponds to a key-value pair, and the boolean value true is converted to lowercase true (the TOML specification itself uses lowercase). In this example, all fields are at the top level, so TOML doesn't require curly braces, making the structure clear at a glance.

More Examples: Nested Objects and Arrays

Let's look at a more complex JSON: {"server": {"host": "127.0.0.1", "port": 8080}, "tags": ["dev", "test"]}. After converting to TOML:

[server]
host = "127.0.0.1"
port = 8080

tags = ["dev", "test"]

Here, the server object becomes a TOML table ([server]), with its keys directly following below it. The tags array retains its array syntax; note that elements within a TOML array are separated by commas and the square brackets are on the same line. If you nest another layer of object arrays (like multiple users), TOML will use [[users]] to identify it.

How to Interpret and Use the Results

The TOML text you get after conversion can be directly pasted into your project configuration files (e.g., config.toml). When interpreting the results, note that:
- Top-level keys have no table headers; they are written directly as key-value pairs.
- Nested objects like {"a": {"b": 1}} become an [a] table, with b = 1 underneath it.
- Object arrays (e.g., [{"x":1}, {"x":2}]) become an [[arr]] table, where each array element is a separate table.
- Empty objects and arrays are preserved (as empty tables or empty arrays).
- Important: TOML 1.0 does not support null values, special floating-point values (NaN, Infinity), or extremely large integers (outside the 64-bit signed integer range) from JSON. If you use these in your JSON, the converter will display an "unsupported" prompt and skip the field.

Quick Reference: JSON vs. TOML Syntax Comparison

Common Pitfalls and Best Practices

1. Unquoted keys: In TOML, if a key name contains special characters (like dots or spaces), it must be enclosed in double quotes; standard alphanumeric keys can be written directly. However, JSON keys must always have double quotes. The converter handles this automatically, but you should know that the resulting keys won't have unnecessary colons.
2. Number format differences: 1.0 in JSON will be converted to 1.0; 1 will be converted to the integer 1. TOML distinguishes between integers and floats, whereas JSON only has the Number type. The converter will try to keep it as is, and TOML also supports scientific notation like 1e2.
3. Boolean case sensitivity: TOML requires boolean values to be lowercase true/false, while JSON parsers might allow uppercase or lowercase. Our converter strictly outputs lowercase.
4. Dates and times: JSON typically uses strings to represent dates, while TOML has native date-time types (e.g., 1979-05-27T07:32:00Z). If you use an ISO 8601 formatted string in JSON, the converter will not automatically recognize it and will still treat it as a string. Manual adjustment is required.
5. Deep nesting: TOML does not limit the depth of nesting, but readability drops after 4-5 levels. If your JSON is deeply nested, the conversion result will feature multiple [foo.bar.baz] headers, so pay attention to maintainability.

Frequently Asked Questions (FAQ)

Q1: Will data be lost after conversion?
A: In most cases, data is fully preserved. However, TOML does not support null, NaN, Infinity, or integers larger than 2^63-1. These fields will be skipped or trigger a warning.

Q2: Are large JSON files supported?
A: Online tools are limited by browser memory, so we recommend files under 2MB. For extremely large JSON files, it's better to use local processing tools.

Q3: My JSON array is full of strings, why is it still an array after conversion?
A: TOML naturally supports string arrays. The format remains unchanged after conversion, except that quotes are standardized to double quotes (TOML requires strings to use double quotes).

Q4: Can the converted TOML be used directly in Rust's toml crate or Python's tomllib?
A: Yes, our output complies with the TOML v1.0 specification, and most mainstream language parsers can read it correctly.

Q5: Why does my JSON have comments (//)?
A: Standard JSON does not support comments. If you pasted from an editor or a JSONC file with comments, please remove the comments before pasting; otherwise, the converter will report a JSON syntax error.

Q6: Will this tool store my data?
A: All conversions are done locally in your browser. Nothing is uploaded to our servers, and your data never leaves your computer.

Limitations and Boundaries

This converter is based on the TOML v1.0 specification (toml.io/en/v1.0.0). It is not suitable for the following scenarios:
- JSON that needs to retain null values (TOML has no equivalent type; we recommend changing them to empty strings or default values).
- JSON containing comments (non-standard; must be manually cleaned before conversion).
- Extremely large or deeply nested JSON (over 10 levels may impact output readability).
- Financial numbers requiring extremely high precision (TOML floats use 64-bit double precision, consistent with JSON, but please verify separately for scientific computing scenarios).
If you find the conversion results are not as expected, please check if your JSON strictly follows the JSON format (e.g., keys must have double quotes, and there can be no trailing commas).

Now you can try your own data in the converter above.