JSON vs YAML vs TOML: where XML still fits

The same service in four grammars

These snippets express similar intent, not byte-for-byte interchangeable data. The XML version makes that distinction visible: without a schema, its numbers and booleans are text, and repeated ports are elements rather than an array value.

{
  "service": {
    "name": "api",
    "ports": [8080, 8081],
    "debug": false
  }
}

service:
  name: api
  ports:
    - 8080
    - 8081
  debug: false

[service]
name = "api"
ports = [8080, 8081]
debug = false

<config>
  <service>
    <name>api</name>
    <ports>
      <port>8080</port>
      <port>8081</port>
    </ports>
    <debug>false</debug>
  </service>
</config>

Where each pair differs

YAML vs JSON: authoring comfort or interchange certainty

JSON has a small data model and near-universal library support. Its quotes and braces are noisy in hand-written files, but they leave relatively little room for a reader to wonder where a value begins. That makes JSON a sound default for APIs, generated artifacts, and stdout that another command will consume.

YAML removes much of that punctuation and adds comments, block strings, anchors, aliases, tags, and multi-document files. Those features help in a large manifest, but they also mean “YAML support” is not one perfectly uniform behavior. Scalar typing can vary with the YAML version and library. Quote a value when it must stay a string, and test with the same parser used in production.

YAML vs TOML: two approaches to human-edited config

YAML mirrors deeply nested objects and long sequences compactly. TOML organizes configuration around named tables and key/value assignments. TOML is often easier to audit for a modest application config because strings are quoted and date/time values have explicit types. It has no native null, and deeply nested or highly repetitive structures can become table-heavy.

Pick YAML when the surrounding platform already speaks YAML or the file benefits from its document features. Pick TOML when you own the application boundary and the configuration naturally looks like sections of settings. Choosing TOML only to avoid YAML is not a design requirement; choosing it because the data fits tables is.

TOML vs JSON: configuration or transport

TOML comments and table headers make it friendlier for configuration maintained in a repository. JSON wins when the file is generated, crossed between languages, or piped into existing tools. A common, clean split is TOML on disk for settings and JSON on stdout for results.

JSON vs XML: value tree or document tree

JSON models program values: objects, arrays, and scalars. XML models ordered elements containing attributes, child elements, and text. XML can represent mixed prose and markup, namespaces, and repeated ordered elements without pretending they are object properties. Mature schema systems are another reason an established XML contract may be worth keeping.

For a new object-shaped API, JSON is usually easier to consume from a shell and a browser. For a document format or an existing XML protocol, converting everything to JSON at the boundary can discard distinctions the XML consumer needs. When comparing JSON vs YAML vs XML, first ask whether the source is configuration, interchange data, or an actual marked-up document.

A practical selection order

1. 01

   Honor the external contract. If Kubernetes, a package manager, an API, or a business partner requires a format, compatibility outweighs personal syntax preferences.

2. 02

   Use JSON between programs unless another model is needed. It has broad tooling, a small conceptual surface, and works naturally with jq and command-line pipelines.

3. 03

   For human-owned config, compare the shape. TOML is strong for sections of application settings. YAML is strong for large, nested manifests and ecosystems built around YAML. JSON is reasonable when the file is mostly generated.

4. 04

   Keep XML when document semantics are real. Attributes, mixed content, namespaces, element order, or an existing schema are requirements, not cosmetic syntax.

5. 05

   Separate streaming from format preference. A continuous sequence of records needs framing. Use NDJSON or JSONL when each record is JSON and should move independently.

Convert YAML, TOML, and XML to JSON with jc-rs

JSON needs no jc-rs parser when it is already JSON. For the other three formats, choose the parser that matches the input and pipe the resulting JSON wherever it needs to go.

cat config.yaml | jc-rs --yaml --pretty

cat config.toml | jc-rs --toml --pretty

cat document.xml | jc-rs --xml --pretty

All three parser pages include their accepted input and a real output example. If you do not have the binary yet, start with the installation options.

Conversion is useful; round-tripping is a different promise

Converting a format into JSON gives downstream tools a common value model. It does not preserve every source-level choice. Treat the JSON as a derived representation unless you have tested the exact return trip.

• Comments and layout disappear. JSON has nowhere standard to store YAML and TOML comments, XML comments as editorial placement, quoting style, or the author's whitespace.
• YAML can exceed JSON's model. Tags, aliases, non-string mapping keys, and library-specific scalar resolution need a mapping decision before they become JSON.
• TOML has types JSON lacks. Dates and times need an agreed string, number, or companion-field representation; TOML also has no null to receive a JSON null.
• XML is not a JSON object with different brackets. Attributes, sibling order, namespaces, mixed text, and repeated elements require a convention. Two converters can choose different, internally consistent shapes.
• Duplicate names are a data-quality problem. Do not rely on “last value wins.” Reject duplicate JSON object names and YAML mapping keys at ingestion, and let TOML's redefinition errors surface.

Common questions