Moving Configuration Between TOML, JSON and YAML: What Survives the Trip

Your CI pipeline emits JSON. Your deployment manifest is YAML. Your local dev config is TOML. You need to move a value from one to the other. You run a converter. The number of results is the same. The structure looks right. You commit it, and something breaks two days later — a date is now a string, a comment warned someone about a dangerous value, a multiline SQL string is now a single line that breaks your query.

Format conversion is lossy in ways that are easy to miss.

The TOML to JSON Converter handles the translation for you — but knowing what it preserves and what it cannot is what prevents the surprise.

What each format can express

Before converting, know what you are working with:

Feature	JSON	YAML	TOML
Comments	No	Yes	Yes
Trailing commas	No	Yes	Yes
Trailing newlines in strings	No	Folded	Preserved
Inline tables	Yes (objects)	Yes (flow)	Yes
Multiline strings	No (use \n)	Folded or literal (`	`)
Date/time types	Strings only	Often strings	First-class types
Keys without quotes	No	Yes	Yes (simple)

The "No" cells are where loss happens. JSON simply cannot represent a comment. JSON has no multiline string syntax. These features vanish in any conversion into JSON.

TOML to JSON: the most common loss points

Comments are dropped. Every # line in TOML disappears. In JSON, there is nowhere to put it.

Dates become strings. TOML's released = 2024-01-15 is a proper date type. JSON has no date type — it becomes "2024-01-15". The semantic difference is invisible in most parsers but matters if your code is checking typeof or running a schema validator that expects a string type.

Multiline strings are a conversion judgment call. TOML's literal string with \ at the end of a line strips the newline:

script = "\
  SELECT * \
  FROM users \
  WHERE active = true"

This produces a single-line SQL query in TOML. JSON has no equivalent multiline syntax, so the converter has to either fold it into one line (losing readability) or emit \n escapes. Either way, the result is not the same as the TOML source.

Inline tables and arrays translate cleanly. TOML's { host = "localhost", port = 5432 } becomes { "host": "localhost", "port": 5432 } — identical structure.

# TOML
[database]
connection = { host = "localhost", port = 5432, ssl = false }

# JSON (equivalent)
{
  "database": {
    "connection": {
      "host": "localhost",
      "port": 5432,
      "ssl": false
    }
  }
}

YAML to TOML: watch the types

YAML 1.1 parsers treat bare yes, no, on, off, true, and false as booleans. TOML also has booleans. So far so good. But YAML also parses 0x1a, 1.2e3, and 1_000_000 as numbers — TOML follows JSON's number rules and does not support underscores or hex in normal form.

# YAML — valid
timeout: 0x3c    # hex: 60
rate: 1_000_000  # underscored integer

These will not parse as TOML numbers. You must quote them as strings or rewrite them.

Dates in YAML are another trap. YAML parsers vary on whether 2024-01-15 is a date object or a string. TOML requires an explicit type. If your YAML file has a bare date that your parser was treating as a string, TOML will accept it as a date — and downstream code expecting a string will break.

Practical round-trip checklist

Before you convert and deploy:

1. Search for # and // in the source. Find every comment. Decide if each one is documenting something the code cannot express otherwise. If so, you need to move it into the data itself or a separate docs file.
2. Check for date fields. TOML dates converted to JSON become strings. Validate that downstream code handles this.
3. Check for multiline strings. SQL queries, regexes, and shell scripts in TOML literal strings are common. The TOML to JSON Converter will emit escaped \n characters — verify your parser handles them.
4. Validate the output. Run the converted file through a validator before committing it. A TOML output should parse without error; a JSON output should pass any schema you apply.
5. Audit keys that look like numbers. 08 in YAML might be an octal. TOML rejects leading-zero integers. Quote it if needed.

One-way or round-trip?

Converting from YAML to JSON for a CI system that generates it once is low risk — the CI never reads the YAML again. Converting a file you will maintain in two formats simultaneously is high risk: every edit requires editing both files and re-auditing the loss points. If you need two formats of the same config, generate one from the other in a build step rather than maintaining them by hand.

Use the TOML to JSON Converter to translate your Cargo.toml or pyproject.toml for a JSON-consuming tool, then validate the output with the appropriate validator before deploying.