JSON to TOML Converter

Understanding JSON and TOML

JSON (JavaScript Object Notation) is the most widely used data-interchange format on the web. It represents data as nested key-value pairs, arrays, and primitive values (strings, numbers, booleans, and null). JSON is natively supported by JavaScript and has mature parsing libraries in every major programming language. Its flexibility makes it suitable for APIs, databases, and configuration files alike. For a comprehensive overview of JSON syntax, data types, and validation rules, visit our JSON guide.

TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read and write thanks to its clear, minimal syntax. Created by Tom Preston-Werner (co-founder of GitHub), TOML maps unambiguously to a hash table and is intended to be parsed into data structures in a wide range of languages. TOML is the standard configuration format for Rust projects (Cargo.toml), Python packaging (pyproject.toml), Hugo static sites, Netlify deployments, and many other tools. Unlike JSON, TOML supports comments, has native date/time types, and uses sections (tables) that make hierarchical configuration intuitive. To learn more about TOML syntax, tables, and array of tables, see our TOML guide.

Converting JSON to TOML bridges the gap between a general-purpose data format and a purpose-built configuration format. While JSON is excellent for machine-to-machine communication, TOML is optimized for human readability in configuration scenarios. This converter handles the structural translation automatically, mapping JSON objects to TOML tables and arrays of objects to TOML arrays of tables.

Why Convert JSON to TOML?

While JSON is versatile, there are many situations where TOML is the expected or preferred format. Here are the most common real-world reasons to convert JSON to TOML:

• Creating Rust Cargo.toml from JSON package metadata. Rust's package manager, Cargo, requires a Cargo.toml manifest file. If you have package metadata stored in JSON (from a registry API, a CI pipeline, or a code generator), converting it to TOML lets you produce a valid Cargo manifest directly.
• Generating Python pyproject.toml files. The Python packaging ecosystem has adopted pyproject.toml as the standard for build configuration (PEP 518, PEP 621). If your tooling outputs JSON, you need to convert it to TOML to create or update pyproject.toml.
• Configuring Hugo static sites. Hugo supports JSON, YAML, and TOML for site configuration, but TOML is the default and most commonly documented format. Converting your existing JSON config to TOML aligns with Hugo community conventions and examples.
• Setting up Netlify or Cloudflare Pages deployments. Services like Netlify use netlify.toml for build and redirect configuration. If you generate deployment settings programmatically as JSON, converting to TOML produces a ready-to-commit config file.
• Improving readability of configuration files. TOML supports comments and has a cleaner syntax for nested sections compared to JSON. Converting a complex JSON config to TOML makes it easier for team members to review, edit, and maintain the configuration by hand.

How the Conversion Works

The converter follows a structured process to transform your JSON data into well-formed TOML output:

1. Parse and validate the input JSON to ensure it is syntactically correct.
2. Check the root type. TOML requires the root to be an object (table). If the root is an array, it is wrapped in an items key to produce a valid TOML document.
3. Map JSON objects to TOML tables. Each nested object becomes a [table] section with its own key-value pairs beneath it.
4. Map arrays of objects to TOML arrays of tables. These use the [[table]] double-bracket syntax, which is TOML's way of representing repeated structured entries.
5. Convert primitive values to their TOML equivalents: strings remain quoted, numbers and booleans are written without quotes, and null values are omitted.
6. Output the formatted TOML with proper indentation and section ordering.

The table below summarizes how each JSON construct maps to its TOML equivalent:

Before and After Example

Below is a practical example showing a JSON package configuration being converted to a TOML format similar to what you would find in a Cargo.toml or pyproject.toml file.

{
  "package": {
    "name": "my-app",
    "version": "1.2.0",
    "authors": [
      "Alice <alice@example.com>",
      "Bob <bob@example.com>"
    ],
    "description": "A sample application"
  },
  "dependencies": [
    {
      "name": "serde",
      "version": "1.0",
      "features": ["derive"]
    },
    {
      "name": "tokio",
      "version": "1.28",
      "features": ["full"]
    }
  ],
  "build": {
    "optimize": true,
    "target": "release"
  }
}

[package]
name = "my-app"
version = "1.2.0"
authors = [
  "Alice <alice@example.com>",
  "Bob <bob@example.com>",
]
description = "A sample application"

[[dependencies]]
name = "serde"
version = "1.0"
features = ["derive"]

[[dependencies]]
name = "tokio"
version = "1.28"
features = ["full"]

[build]
optimize = true
target = "release"

Notice how the nested package object became a [package] table, the dependencies array of objects became [[dependencies]] array of tables (each entry gets its own double-bracket section), and primitive arrays like authors and features remained as inline TOML arrays. The build object became another [build] table with its key-value pairs.

Tips and Best Practices

Related Tools

Explore other converters and resources that complement JSON-to-TOML conversion: