Every software project needs configuration, and the format you choose affects readability, tooling support, and the likelihood of subtle bugs. JSON, YAML, and TOML are the three most common choices for configuration files, each with strengths that make it ideal for certain use cases and weaknesses that make it frustrating in others.
JSON: The Universal Standard
JSON is everywhere. Every programming language has a JSON parser, every API speaks JSON, and every developer can read it. For configuration, JSON is unambiguous — there is exactly one way to represent any given data structure. The downside is verbosity: JSON requires quotes around every key, does not support comments, and nested structures quickly become hard to read. For simple, machine-edited configs, JSON is excellent. For configs that humans frequently edit, it can be painful.
YAML: Human-Readable but Treacherous
YAML was designed for human readability, and it succeeds beautifully in simple cases. Indentation-based nesting, no quotes on most strings, and comment support make YAML configs pleasant to read and write. But YAML’s flexibility is also its weakness. Implicit type coercion turns `no` into a boolean, `3.0` into a float, and `1_000` into an integer — all without warning. Norway’s country code (`NO`) famously evaluates to `false`. These gotchas have caused real production incidents.
TOML: The Middle Ground
TOML aims to be a minimal, obvious configuration format. It supports comments, has explicit typing, and avoids YAML’s implicit coercion problems. Tables and arrays of tables handle nested structures cleanly. The syntax is straightforward enough that most developers can read a TOML file without documentation. TOML’s main limitation is that deeply nested structures become verbose, making it less suitable for complex hierarchical configs.
When to Use Each Format
Use JSON when interoperability matters most, when configs are primarily machine-generated, or when you need strict schema validation. Use YAML for Kubernetes manifests, CI/CD pipelines, and other cases where the ecosystem expects it, but be vigilant about type coercion. Use TOML for application configuration files, especially in Rust, Python, and Go projects where TOML support is excellent.
Comments: The Underrated Feature
JSON’s lack of comment support is its biggest weakness for configuration files. Comments in config files explain why a setting has a particular value, document valid ranges, and prevent future developers from changing things they should not. Both YAML and TOML support comments, giving them a significant advantage for configs that humans maintain.
Viewing and Editing Config Files on the Go
ParseLab for iOS lets you open, view, and edit JSON, YAML, and other data formats directly on your iPhone or iPad. Its syntax-highlighted tree view makes it easy to navigate complex nested configurations, compare formats side by side, and catch structural issues before they cause problems in production.