What is TOML?

TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy to read and write. It maps cleanly to hash tables and is used by tools like Cargo (Rust), Poetry and pyproject.toml (Python), Hugo, Netlify, and many other modern development tools. TOML supports strings, integers, floats, booleans, dates, arrays, and tables with a clear, unambiguous syntax that avoids the indentation pitfalls of YAML.

Why convert TOML to JSON?

Converting TOML to JSON is useful when you need to process configuration data in languages or tools with better JSON support, integrate TOML-based configs into JSON-consuming APIs, or validate and inspect the parsed structure of a TOML file. JSON's widespread tooling ecosystem — including JSON Schema validation, jq querying, and universal language support — makes it a convenient intermediate format for programmatic access to config data.

TOML vs JSON syntax comparison

TOML uses [section] headers for nested objects and key = value syntax for assignments. JSON uses curly braces and quoted keys. For example, a TOML section like [database] followed by host = "localhost" and port = 5432 becomes {"database": {"host": "localhost", "port": 5432}} in JSON. TOML also supports inline tables, arrays of tables with [[double brackets]], and dotted keys like server.host for nested access without section headers.

# Python — TOML to JSON (3.11+ has built-in tomllib)
import tomllib, json
with open('config.toml', 'rb') as f:
    data = tomllib.load(f)
print(json.dumps(data, indent=2))

// JavaScript — TOML to JSON with smol-toml
import { parse } from 'smol-toml';
const toml = '[database]\nhost = "localhost"\nport = 5432';
const json = JSON.stringify(parse(toml), null, 2);
// { "database": { "host": "localhost", "port": 5432 } }

Tools and ecosystems that use TOML

TOML has become the standard config format in several major ecosystems. Rust uses Cargo.toml for package management. Python adopted pyproject.toml (PEP 518/621) for project metadata, replacing setup.py and setup.cfg. Hugo uses config.toml for site configuration. Netlify uses netlify.toml for deployment settings. Deno uses deno.json but supports TOML imports. The format's growth is driven by its unambiguous parsing — unlike YAML, TOML rarely produces surprising behavior from whitespace or implicit type coercion.

TOML features not available in JSON

TOML supports several features that JSON lacks. Comments (with #) let you document configuration decisions inline. Native date and datetime types are built into the spec. Multi-line basic strings with triple quotes handle long values cleanly. Literal strings with single quotes disable escape sequences. Arrays of tables with [[section]] represent repeated structures like multiple server blocks. During conversion to JSON, comments are dropped, dates become ISO 8601 strings, and all special string types become regular JSON strings.