Convert TOML to JSON

Why Convert TOML to JSON?

Converting TOML to JSON is one of the most common and practical configuration format conversions. JSON is the universal data interchange format of the web, supported natively by JavaScript and virtually every programming language. When your TOML configuration data needs to be consumed by web APIs, JavaScript applications, or tools that expect JSON input, this conversion provides a seamless bridge between the two formats.

TOML and JSON share fundamental similarities in their data models: both support objects/tables, arrays, strings, numbers, and booleans. TOML tables map directly to JSON objects, TOML arrays to JSON arrays, and primitive values convert one-to-one. The key difference is that TOML dates become JSON strings (since JSON has no date type) and TOML comments are stripped (since JSON does not support comments).

This conversion is especially valuable in polyglot development environments where Rust or Python projects use TOML for configuration but need to share settings with Node.js services, web frontends, or REST APIs that consume JSON. Rather than maintaining duplicate configuration files, teams can use TOML as the source of truth and generate JSON for consumption by other systems.

JSON's massive ecosystem of validation tools (JSON Schema), query languages (JSONPath, jq), and processing libraries makes it an ideal target format for configuration data that needs to be validated, queried, or transformed programmatically. Converting TOML to JSON unlocks access to this entire ecosystem while preserving the human-friendly TOML format for direct editing.

Key Benefits of Converting TOML to JSON:

• Universal Compatibility: JSON is supported by every programming language
• Web API Integration: Use TOML config data in REST/GraphQL APIs
• JavaScript Native: JSON.parse() in every browser and Node.js
• Validation: Apply JSON Schema validation to your config data
• Tooling Ecosystem: Access jq, JSONPath, and thousands of JSON tools
• Database Storage: Store in MongoDB, PostgreSQL JSONB, and more
• Lossless Mapping: TOML data model maps cleanly to JSON

Practical Examples

Example 1: Rust Project Config to JSON

Input TOML file (Cargo.toml):

[package]
name = "myapp"
version = "1.0.0"
edition = "2021"
authors = ["Dev <[email protected]>"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.28", features = ["full"] }
axum = "0.6"

Output JSON file (Cargo.json):

{
  "package": {
    "name": "myapp",
    "version": "1.0.0",
    "edition": "2021",
    "authors": ["Dev <[email protected]>"]
  },
  "dependencies": {
    "serde": {
      "version": "1.0",
      "features": ["derive"]
    },
    "tokio": {
      "version": "1.28",
      "features": ["full"]
    },
    "axum": "0.6"
  }
}

Example 2: Application Settings for API

Input TOML file (config.toml):

[server]
host = "0.0.0.0"
port = 3000
cors_origins = ["https://app.example.com", "https://admin.example.com"]

[auth]
jwt_secret = "change-me-in-production"
token_expiry = 3600
refresh_enabled = true

[features]
dark_mode = true
beta_features = ["new-dashboard", "ai-search"]

Output JSON file (config.json):

{
  "server": {
    "host": "0.0.0.0",
    "port": 3000,
    "cors_origins": [
      "https://app.example.com",
      "https://admin.example.com"
    ]
  },
  "auth": {
    "jwt_secret": "change-me-in-production",
    "token_expiry": 3600,
    "refresh_enabled": true
  },
  "features": {
    "dark_mode": true,
    "beta_features": ["new-dashboard", "ai-search"]
  }
}

Example 3: pyproject.toml to JSON for CI/CD

Input TOML file (pyproject.toml):

[project]
name = "analytics-lib"
version = "2.0.0"
requires-python = ">=3.10"

[project.dependencies]
numpy = ">=1.24"
pandas = ">=2.0"

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I"]

Output JSON for CI/CD pipeline:

{
  "project": {
    "name": "analytics-lib",
    "version": "2.0.0",
    "requires-python": ">=3.10",
    "dependencies": {
      "numpy": ">=1.24",
      "pandas": ">=2.0"
    }
  },
  "tool": {
    "ruff": {
      "line-length": 100,
      "target-version": "py310",
      "lint": {
        "select": ["E", "F", "I"]
      }
    }
  }
}

Frequently Asked Questions (FAQ)

Q: Is the conversion from TOML to JSON lossless?

A: Nearly lossless. TOML's core data types (strings, integers, floats, booleans, arrays, tables) map directly to JSON equivalents. Two things are lost: TOML comments (JSON does not support comments) and TOML date/time values (which become JSON strings since JSON has no date type). The structural data is fully preserved.

Q: How are TOML dates handled in JSON?

A: TOML supports native date, time, and datetime types (RFC 3339 format). Since JSON has no date type, these values are converted to ISO 8601 formatted strings. For example, TOML's created = 2024-01-15T10:30:00Z becomes JSON's "created": "2024-01-15T10:30:00Z". Applications consuming the JSON can parse these strings back into date objects.

Q: Why would I use TOML instead of writing JSON directly?

A: TOML is much more pleasant for humans to read and edit: it supports comments, has cleaner syntax without excessive braces and commas, allows multiline strings, and provides native date types. Many teams use TOML as the human-editable source and convert to JSON for machine consumption. This gives you the best of both worlds.

Q: Can I use the JSON output with JSON Schema validation?

A: Yes. Once converted to JSON, you can validate the data against a JSON Schema to ensure configuration values meet your requirements. This is a powerful pattern: maintain human-friendly TOML files, convert to JSON, then validate with JSON Schema in your CI/CD pipeline to catch configuration errors early.

Q: How do TOML inline tables convert to JSON?

A: TOML inline tables (e.g., serde = { version = "1.0", features = ["derive"] }) convert to regular JSON objects. There is no distinction between inline and regular tables in the output since JSON has only one object type. The result is a clean nested JSON object with the same key-value structure.

Q: What about TOML integer types and JSON numbers?

A: TOML distinguishes between integers and floats, and both map to JSON numbers. However, JSON has a precision limit for large numbers (safe integer range is up to 2^53). Very large TOML integers may need to be converted to strings in JSON to prevent precision loss. Standard configuration values are well within safe range.

Q: Can I process the JSON output with jq or similar tools?

A: Absolutely. Once in JSON format, you can use jq for filtering and transformation, JSONPath for querying, and any JSON processing library. For example, jq '.dependencies | keys' would extract all dependency names. This is one of the primary reasons for converting TOML to JSON.

Q: How does this differ from TOML to YAML conversion?

A: Both JSON and YAML can represent the same data structure from TOML. JSON is more widely supported in web APIs and JavaScript ecosystems, while YAML is more human-readable and supports comments. Choose JSON for machine consumption and API integration; choose YAML if the output needs to be human-editable and you need comments.