Convertisseur TOML vers JSON

TOML to JSON Converter: Bidirectional Format Translation

TOML (Tom's Obvious, Minimal Language) and JSON (JavaScript Object Notation) serve complementary roles in modern software development. TOML excels as a human-friendly configuration format with native support for dates, multi-line strings, and hierarchical tables, while JSON dominates as the universal data interchange format for APIs, tooling, and programmatic access. Converting between these two formats is a frequent need when integrating configuration systems with JSON-consuming pipelines, migrating legacy configs, or generating machine-readable representations of human-authored settings.

This converter performs bidirectional translation between TOML and JSON, preserving data structure and semantics while handling the type mapping differences between the two formats. Unlike a TOML validator or formatter that focuses on syntax checking and beautification within the TOML format itself, this tool bridges the gap between two distinct serialization formats, enabling seamless interoperability between TOML-native tooling (Cargo, pyproject.toml, Hugo) and JSON-native ecosystems (web APIs, JavaScript toolchains, cloud services).

Data Type Mapping Between TOML and JSON

TOML and JSON have overlapping but non-identical type systems. Understanding how types map between formats is essential for predictable conversion results. JSON supports strings, numbers, booleans, null, arrays, and objects. TOML adds native datetime types, distinguishes between integers and floats, supports multi-line and literal strings, and provides inline tables and arrays of tables as structural primitives.

When converting TOML to JSON, the following type mappings apply: TOML integers map to JSON numbers (with potential precision loss for values exceeding 2^53), TOML floats map to JSON numbers, TOML booleans map directly to JSON booleans, and TOML strings map to JSON strings regardless of their original quoting style (basic, literal, multi-line). TOML tables and inline tables both become JSON objects, while arrays of tables become JSON arrays of objects.

The most significant mapping challenge involves TOML's native datetime types: Offset Date-Time (e.g., 2024-01-15T10:30:00Z), Local Date-Time, Local Date, and Local Time. JSON has no native date type, so these values are serialized as ISO 8601 strings during TOML-to-JSON conversion. When converting back from JSON to TOML, the converter detects ISO 8601 patterns in string values and can optionally restore them to native TOML datetime types, though this requires heuristic detection since JSON strings are ambiguous.

TOML-Specific Structures and Their JSON Equivalents

TOML's table syntax provides multiple ways to express nested structures that all collapse into the same JSON representation. A dotted key like database.server.host = "localhost" produces the same JSON as explicit table headers [database.server] followed by host = "localhost". Similarly, inline tables point = { x = 1, y = 2 } produce identical JSON objects to their expanded multi-line equivalents. The converter normalizes all these structural variants into canonical JSON objects.

Arrays of tables, defined with double-bracket syntax [[products]], represent a TOML feature without a direct JSON syntactic parallel. Each double-bracket section appends a new object to a JSON array. This pattern is common in configuration files that define lists of similar entities such as server endpoints, dependency specifications, or plugin configurations. The converter correctly handles nested arrays of tables and mixed table/array-of-table hierarchies.

When converting from JSON to TOML, the converter must decide between inline tables and standard tables, between dotted keys and explicit headers, and between single-line and multi-line strings. This tool uses heuristics based on nesting depth and content length: shallow objects with few keys become inline tables, while deeply nested structures use explicit table headers for readability. Arrays of objects always use the double-bracket array-of-tables syntax.

Lossless vs Lossy Conversion Considerations

Bidirectional conversion between TOML and JSON is not always perfectly lossless due to fundamental differences in the formats' type systems and structural semantics. TOML-to-JSON conversion is generally lossless in terms of data values but loses formatting information such as comments, whitespace style, key ordering preferences, and the distinction between inline and standard tables. TOML comments (lines starting with #) have no JSON equivalent and are discarded during conversion.

JSON-to-TOML conversion can be fully lossless for data that fits within TOML's type constraints. However, JSON's null value has no TOML equivalent since TOML requires all values to be present and typed. The converter handles null values by either omitting the key entirely (lossy but idiomatic) or representing it as an empty string with a comment indicating the original null (preserving intent but altering the value). Mixed-type arrays in JSON, such as [1, "two", true], are valid JSON but invalid TOML, which requires homogeneous arrays.

For round-trip fidelity (TOML → JSON → TOML), the converter preserves key ordering and attempts to reconstruct table structure from the JSON hierarchy. However, comments, formatting choices, and structural preferences (inline vs expanded) cannot survive the round trip through JSON. For workflows requiring comment preservation, consider using TOML-aware tools that operate on the AST rather than converting through an intermediate format.

Use Cases for TOML-JSON Conversion

Tooling interoperability is the primary driver for TOML-JSON conversion. Many build systems and deployment platforms consume JSON configuration but developers prefer authoring in TOML for its readability. Converting pyproject.toml to JSON enables integration with CI/CD systems that parse JSON natively. Similarly, converting Rust's Cargo.toml to JSON allows programmatic dependency analysis using standard JSON tools like jq.

Pipeline integration represents another common scenario. Data pipelines often use JSON as their interchange format, but configuration for pipeline stages may be authored in TOML for clarity. Converting TOML configs to JSON at build time allows the pipeline runtime to consume a single format while developers maintain human-friendly source files. This pattern is used in Hugo static sites, Netlify configurations, and various infrastructure-as-code workflows.

Configuration migration is the third major use case. Organizations moving from JSON-based configuration (common in Node.js ecosystems) to TOML (increasingly adopted in Python, Rust, and Go ecosystems) need to convert existing JSON configs to TOML while preserving all values and structure. The reverse migration (TOML to JSON) occurs when integrating with systems that only accept JSON input, such as many REST APIs, cloud provider CLIs, and JavaScript-based toolchains.

Code Examples

TOML to JSON conversion — configuration file example

# Input TOML (pyproject.toml style)
[project]
name = "my-app"
version = "1.2.0"
requires-python = ">=3.9"
authors = [
  { name = "Alice", email = "alice@example.com" }
]

[project.dependencies]
requests = ">=2.28"
pydantic = ">=2.0"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--strict-markers"

[[tool.mypy.overrides]]
module = "legacy.*"
ignore_errors = true

Output:

{
  "project": {
    "name": "my-app",
    "version": "1.2.0",
    "requires-python": ">=3.9",
    "authors": [
      { "name": "Alice", "email": "alice@example.com" }
    ],
    "dependencies": {
      "requests": ">=2.28",
      "pydantic": ">=2.0"
    }
  },
  "tool": {
    "pytest": {
      "ini_options": {
        "testpaths": ["tests"],
        "addopts": "--strict-markers"
      }
    },
    "mypy": {
      "overrides": [
        { "module": "legacy.*", "ignore_errors": true }
      ]
    }
  }
}

JSON to TOML conversion — restoring structured config

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp_production",
    "ssl": true,
    "pool": { "min": 2, "max": 10 }
  },
  "servers": [
    { "name": "web-1", "ip": "10.0.0.1", "role": "primary" },
    { "name": "web-2", "ip": "10.0.0.2", "role": "replica" }
  ]
}

Output:

[database]
host = "localhost"
port = 5432
name = "myapp_production"
ssl = true
pool = { min = 2, max = 10 }

[[servers]]
name = "web-1"
ip = "10.0.0.1"
role = "primary"

[[servers]]
name = "web-2"
ip = "10.0.0.2"
role = "replica"

Standards & Specifications

• TOML v1.0.0 Specification — The official TOML language specification defining syntax, types, and grammar rules
• RFC 8259 (JSON) — The JSON data interchange format specification used as the target/source format
• ISO 8601 (Date and Time) — Date-time representation standard used when serializing TOML datetime types to JSON strings