All articles

JSON ↔ YAML/CSV/XML/TOML: when and why to convert

JSON isn't the only structured data format in daily use — YAML, CSV, XML, and TOML each grew out of a different ecosystem, and converting between them is a routine part of working across tools that don't agree on a format.

What each format is actually for

  • YAML — indentation instead of brackets, the default for CI/CD pipelines, Kubernetes manifests, and Docker Compose files.
  • CSV — flat and tabular, the lowest common denominator for spreadsheets and data analysis tools.
  • XML — older, with attributes and namespaces, still the backbone of SOAP services and plenty of enterprise middleware.
  • TOML — designed to be unambiguous and easy to hand-edit, best known from Rust's Cargo.toml.

The "Norway problem": a real bug that shaped YAML 1.2

In YAML 1.1, an unquoted NO is parsed as the boolean false, because yes/no/on/off were all treated as boolean literals. That collided head-on with ISO 3166-1's two-letter country code for Norway, which is also NO — country lists in YAML config files would silently lose Norway, converting it to false instead of a string. The bug report became well-known enough in the YAML community that it's referred to by name, and it's a real reason YAML 1.2 narrowed the set of implicit booleans. The practical fix hasn't changed: quote any value that must stay a string.

Losses in conversion

Not every conversion is equally safe. JSON → CSV throws away nesting: deep objects and variable-length arrays don't fit a rectangular table, so they get flattened or simplified. JSON ↔ YAML and JSON ↔ TOML are nearly always lossless, since both formats support nested structures the same way JSON does.

Why this comes up in practice

  • Moving a config from a tool that expects YAML into one that expects JSON, or the reverse.
  • Exporting API data to CSV for a quick look in a spreadsheet.
  • Bridging a legacy XML/SOAP system with a modern JSON-based API.
Try the tool