EasyExtract

Uncategorized

How to Convert TOML to JSON and YAML: Config Parsing Guide

By · · 10 min read

To convert TOML configuration files to JSON and YAML without server uploads, parse the TOML syntax tree into typed data nodes, map tables and table arrays to structured hierarchies, and serialise the output to valid JSON or YAML. Client-side browser extraction parses build manifests and secrets locally in memory without transmitting data over the network.

Key Definitions: Understanding the TOML v1.0.0 Specification and Data Mappings

Tom’s Obvious, Minimal Language (TOML) is an explicit, strongly typed configuration format engineered for human readability and unambiguous data mapping. Standardised under the TOML v1.0.0 Specification by Tom Preston-Werner, TOML eliminates parsing ambiguities found in older formats:

  • TOML Standard (v1.0.0): The official specification defining lexical grammar, UTF-8 encoding, exact scalar types, and formal tree-parsing semantics.
  • Standard Tables ([table]): Bracketed headers defining key groups that map directly to JSON objects ({ ... }) or nested YAML mappings. Standard tables scope key-value pairs until the next table declaration.
  • Inline Tables ({ k = v }): Compact, single-line key-value definitions inside curly braces. They map directly to JSON objects or YAML flow mappings and remain immutable once declared.
  • Arrays of Tables ([[table]]): Double-bracketed headers representing ordered collections of tables. Each declaration instantiates a new element in a list, mapping to a JSON array of objects ([ { ... }, { ... } ]) or a YAML sequence.
  • JSON Mapping: Structural translation into RFC 8259 JSON. Because JSON lacks native dates and comments, TOML datetimes become ISO 8601 strings and comments are stripped.
  • YAML Mapping: Structural translation into YAML 1.2. YAML natively supports ISO 8601 timestamps, comments, and nested block sequences.

Using an online TOML to JSON and YAML converter enables developers to validate syntax, inspect nested trees, and emit clean JSON and YAML payloads instantaneously.

The TOML Specification vs YAML and JSON: Why Explicit Syntax Prevents Indentation Bugs

Modern software engineering relies on configuration manifests to control build pipelines and cloud runtimes. However, JSON, YAML, and TOML approach syntax design with distinct structural priorities.

JSON prioritises machine-to-machine serialization. It requires braces, brackets, quoted keys, and commas. While universally supported, standard JSON forbids comments, disallows trailing commas, and is error-prone during manual editing.

YAML maximises brevity by replacing delimiters with significant whitespace. However, whitespace scoping introduces fragility into CI/CD pipelines. An accidental space or tab can silently reassign child nodes or break deployments. Furthermore, YAML’s implicit type coercion—such as coercing unquoted yes, no, or country code NO to booleans—causes notorious runtime defects.

TOML eliminates these issues with an explicit, flat-scoping paradigm:

# Explicit table scoping and strict typing in TOML v1.0.0
[server]
host = "127.0.0.1"
port = 8080
country = "NO" # Preserved as a literal string

[server.timeouts]
read_seconds = 30
write_seconds = 60

In TOML, indentation is purely stylistic and carries zero semantic weight. Each table path (such as [server.timeouts]) explicitly declares its namespace address, making Git merge conflicts straightforward to resolve.

Step-by-Step: How to Convert TOML to JSON and YAML in Your Browser

Transforming TOML manifests into portable JSON or YAML can be completed entirely within your web browser through five simple steps:

  1. Open the Local Converter: Navigate to the EasyExtract TOML Extractor. The tool loads a WebAssembly parser locally in your browser memory without contacting external APIs.
  2. Input Your TOML Source Data: Drag and drop your configuration file (such as Cargo.toml or pyproject.toml) into the dropzone, or paste raw TOML text into the editor.
  3. Select Your Desired Format: Choose between formatted JSON (2-space or 4-space indentation), minified JSON for API payloads, or clean YAML 1.2 block mapping.
  4. Verify Type Mappings: Check the live preview to verify that integers, booleans, timestamps, and arrays of tables have mapped accurately.
  5. Export and Download: Copy the converted payload to your clipboard or download the generated .json or .yaml file ready for production deployment.

For cross-format workflows, you can also easily extract data from YAML manifests or parse INI and ENV config keys in your browser.

Managing Cargo.toml (Rust) and pyproject.toml (Python) Configuration Manifests

Rust’s Cargo.toml and Python’s pyproject.toml (PEP 518 / PEP 621) are the two most prominent modern TOML implementations. Converting these manifests into JSON or YAML is essential for CI/CD dependency audits and container automation.

1. Parsing Rust Cargo.toml Manifests

Rust uses Cargo.toml to declare package metadata, compilation targets, and dependencies:

[package]
name = "data-pipeline"
version = "0.4.2"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.35", features = ["full"] }

Converting this manifest to JSON expands inline dependency tables into standard nested objects for programmatic inspection with tools like jq:

{
  "package": {
    "name": "data-pipeline",
    "version": "0.4.2",
    "edition": "2021"
  },
  "dependencies": {
    "serde": { "version": "1.0", "features": ["derive"] },
    "tokio": { "version": "1.35", "features": ["full"] }
  }
}

2. Parsing Python pyproject.toml Manifests

PEP 518 unified Python tool configurations under pyproject.toml. A representative manifest managing build tools and linters looks as follows:

[build-system]
requires = ["hatchling>=1.18.0"]
build-backend = "hatchling.build"

[project]
name = "telemetry-agent"
version = "2.1.0"
dependencies = ["pydantic>=2.0", "httpx>=0.24.0"]

[tool.ruff]
line-length = 100

Converting this file to YAML produces an easily consumable schema for cloud deployment pipelines:

build-system:
  build-backend: hatchling.build
  requires:
    - hatchling>=1.18.0
project:
  dependencies:
    - pydantic>=2.0
    - httpx>=0.24.0
  name: telemetry-agent
  version: 2.1.0
tool:
  ruff:
    line-length: 100

Handling Complex Data Types: ISO 8601 DateTimes, Integers vs Floats, Booleans, and Multiline Literal Strings

TOML features a rich scalar type system that requires precise handling during format translation:

1. Temporal Values (ISO 8601 DateTimes)

TOML supports Offset Date-Times (1979-05-27T07:32:00Z), Local Date-Times (1979-05-27T07:32:00), Local Dates (1979-05-27), and Local Times (07:32:00). When converting to JSON, temporal values are serialised as ISO 8601 strings since JSON lacks a native date type. In YAML 1.2, timestamps are preserved as native timestamp scalars.

2. Integers vs Floating-Point Numbers

TOML differentiates between integers (decimal, hex 0x, octal 0o, binary 0b, with optional underscores 1_000_000) and floats (requiring a dot 3.14 or exponent 1e6, plus inf and nan). In JSON exports, underscores and radix prefixes are normalized to standard base-10 numbers. Special floats like nan and inf are mapped to null.

3. Strict Booleans

TOML booleans must be lowercase: true and false. They translate directly into standard JSON and YAML boolean tokens without risk of ambiguous string coercion.

4. String Variants: Basic, Literal, and Multiline

TOML provides four distinct string delimiters to simplify escaping:

String Type Delimiters Escape Handling Common Use Case
Basic String "..." Standard escapes (\n, \t) Standard property values and URLs
Multiline Basic """...""" Escapes with line-trim (\) Formatted documentation and SQL queries
Literal String '...' No escaping (raw characters) Windows paths and regular expressions
Multiline Literal '''...''' No escaping (raw multiline) Shell scripts and cryptographic certificates

When converting literal strings containing backslashes (such as Windows paths C:\tools\bin) to JSON, the converter automatically escapes backslashes ("C:\\tools\\bin") to ensure valid JSON output.

TOML vs YAML vs JSON vs INI: Complete Configuration Format Comparison Matrix

The matrix below compares the four primary configuration standards across key architectural criteria:

Feature TOML (v1.0.0) YAML (1.2) JSON (RFC 8259) INI / .ENV
Hierarchy Explicit tables ([a.b]) Indentation / whitespace Nested braces ({ }) Flat or 2-level sections
Comments Supported (#) Supported (#) Not supported Supported (; / #)
Typing Strong & explicit Implicit type coercion Basic scalar types Untyped (raw strings)
Schema Complexity Low to Medium High (anchors, tags) Very Low Very Low
Array of Tables Yes ([[array]]) Yes (- key: val) Yes ([ { } ]) No native array support
Primary Use Build configs (Rust, Python) Kubernetes, DevOps CI/CD REST APIs, data storage OS config, runtime .env

For more on extracting flat key-value pairs, see our guide on how to extract environment variables and INI keys.

Exporting TOML to CSV Tables and Flat Dot-Notated Key Paths for CI/CD Pipelines

DevOps workflows often require flattening nested TOML structures for shell scripts or exporting repetitive collections to CSV for audit reports.

1. Extracting Flat Dot-Notated Key Paths

Flattening TOML tables generates dot-notated assignments suitable for injecting parameters into Docker containers or Terraform runs:

# Flat dot-notated parameters extracted from TOML
server.host = "0.0.0.0"
server.port = 8443
server.tls.enabled = true
database.pool.max_connections = 50

2. Converting Arrays of Tables to Tabular CSV

When a configuration contains multiple repeated tables (such as server or user lists), converting them to CSV creates clean tabular data for spreadsheet tools:

[[servers]]
name = "web-node-01"
ip = "192.168.1.10"
active = true

[[servers]]
name = "web-node-02"
ip = "192.168.1.11"
active = false

The resulting CSV output groups uniform fields into tabular columns:

name,ip,active
web-node-01,192.168.1.10,true
web-node-02,192.168.1.11,false

3. Command-Line Automation with Python

For automated Linux pipeline environments, Python 3.11 includes standard library support for parsing TOML via tomllib:

# Automated in-line TOML to JSON conversion with Python 3.11+
import tomllib, json

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

print(json.dumps(data, indent=2))

Common Formatting Errors: Invalid Table Syntax, Duplicate Keys, and Unquoted Strings

Because TOML parsers enforce strict validation, malformed syntax will immediately halt conversion. Below are the most common errors and how to resolve them:

1. Duplicate Key and Table Definitions

TOML prohibits defining the same standard table or property key more than once within the same scope:

# INVALID: Duplicate standard table definition
[database]
host = "127.0.0.1"

[database] # ERROR: Duplicate table definition!
port = 5432

# FIX: Consolidate properties under a single table declaration
[database]
host = "127.0.0.1"
port = 5432

2. Dotted Key Collisions

Defining a dotted key implicitly creates parent tables. Attempting to redeclare that table explicitly later causes a conflict:

# INVALID: Dotted key collision
server.network.port = 8080

[server.network] # ERROR: Table [server.network] was already created!
timeout = 30

# FIX: Declare the table header first, followed by child keys
[server.network]
port = 8080
timeout = 30

3. Bare Keys with Special Characters

Bare keys in TOML may only include alphanumeric characters, underscores, and dashes. Keys with spaces, dots, or colons must be quoted:

# INVALID: Bare keys containing illegal characters
127.0.0.1 = "localhost" # ERROR: Period indicates dotted key path
content type = "application/json" # ERROR: Unquoted whitespace

# FIX: Wrap keys containing special characters in quotes
"127.0.0.1" = "localhost"
"content type" = "application/json"

Privacy and Security: Why Repository Configurations and Build Metadata Must Stay Local in the Browser

Configuration files such as Cargo.toml and pyproject.toml frequently contain sensitive operational metadata:

  • Internal package registry endpoints and authentication variable names.
  • Private corporate IP addresses and internal DNS hostnames.
  • Database schema names, port numbers, and encryption configurations.
  • Proprietary dependency lists revealing system architecture.

Using cloud-based converters uploads sensitive manifests to third-party servers, creating compliance risks under SOC 2 and GDPR. EasyExtract eliminates this risk by parsing files client-side in browser memory using WebAssembly. No data leaves your machine.

Frequently Asked Questions

How do I convert a TOML file to JSON without installing software?

You can convert TOML directly in your browser using EasyExtract. Paste your raw TOML text or upload your file, select JSON export, and the local WebAssembly parser will instantly generate formatted JSON in memory.

What is the difference between a standard table and an inline table in TOML?

A standard table ([table]) spans multiple lines and groups all subsequent keys until the next section header. An inline table ({ k = v }) is defined on a single line and represents an immutable, self-contained map.

Can JSON natively represent TOML datetime formats?

No. JSON does not have a native Date data type. When converting TOML datetime objects (such as Offset Date-Times or Local Dates) to JSON, parsers serialise them as standard ISO 8601 formatted text strings.

How does TOML represent arrays of objects compared to JSON and YAML?

TOML uses the double-bracket Array of Tables syntax ([[items]]). Each occurrence adds a new object element to the array, mapping to "items": [ { ... } ] in JSON and block sequences in YAML.

Why does TOML prevent accidental typing errors compared to YAML?

TOML avoids ambiguous implicit type coercion. In YAML, unquoted words like yes, no, or country code NO are coerced to booleans. In TOML, only lowercase true and false represent booleans.

Can I convert Rust Cargo.toml and Python pyproject.toml manifests directly to YAML?

Yes. Both Cargo.toml and pyproject.toml are valid TOML files. Uploading them into EasyExtract parses all metadata, dependencies, and tables into properly indented YAML manifests.

Are my sensitive configuration keys or internal server IPs uploaded to any server?

No. EasyExtract executes all parsing, tree generation, and serialization entirely within your browser’s local memory. No configuration text, API keys, or IP addresses ever leave your device.

Sources and References

Keep reading