JSON Was Designed for Machines. YAML Was Designed for People. Here Is Why That Matters for Configuration Files.
Ask a developer what is wrong with JSON configuration files and the answers come quickly: the required quotes on every key, the commas that must appear after every item except the last, the inability to add a comment explaining why a setting exists. JSON was designed by Douglas Crockford in March 2001 to transmit data between a Java server and a JavaScript browser client. His company was building what would now be called single-page web applications, and he needed a way to exchange data between the two that was lighter than the XML conventions dominant at the time. JSON was designed for machines reading data from other machines, not for humans maintaining configuration files over years.
YAML was designed to solve a different problem. Clark Evans, Oren Ben-Kiki, and Ingy dot Net began developing the format in 2001 through the yaml-core mailing list, with the explicit design goal of making data files that a human could read and maintain without squinting at punctuation. The name, which originally stood for Yet Another Markup Language and was later changed to the recursive acronym YAML Ain't Markup Language, reflected a deliberate positioning against the XML and JSON conventions that were becoming dominant. The core team's stated design priorities were, in order: readability by humans, portability between programming languages, compatibility with dynamic language native data structures, and support for generic tools. Machine efficiency was not the priority. Human readability was.
The result looks different enough from JSON that switching between them requires a moment of adjustment, but both represent the same underlying information. The question is not which format is better. It is which format is right for the task: JSON for machine exchange, YAML for human maintenance.
What JSON Syntax Adds and YAML Removes
A JSON configuration file for a typical web application sets logging levels, database connection strings, and feature flags. Every string key is in double quotes. Every string value is in double quotes. Every object uses curly braces. Every array uses square brackets. Every item except the last must end with a comma.
The trailing-comma rule is the single most consistent source of JSON editing errors. Add a new setting to the end of a list, and the previous last item now needs a comma that was not there. Remove the last item, and the new last item's trailing comma must be deleted. Automated tools handle this correctly. Humans editing production configuration files under time pressure do not reliably catch it. JSON parsers produce an error and stop; they do not tell you which comma was missing or extra.
YAML eliminates all of this punctuation. Keys are unquoted unless they contain characters that require quoting. Values are unquoted for scalars that have clear types. Lists use a dash and a space before each item, with indentation indicating nesting. Objects use indentation to indicate structure, with no closing braces. Comments begin with a hash character and can appear at the end of any line or on lines of their own. A developer reading a YAML configuration file reads something that resembles structured prose, with visual hierarchy provided by indentation rather than matching brackets.
The whitespace-sensitivity of YAML has a trade-off: indentation errors change the structure. A key indented one space too many may be interpreted as a nested key under the preceding item rather than a sibling. YAML parsers surface these errors, but they can be harder to spot visually than a missing comma in JSON. Teams that use YAML for configuration files typically use linting tools and editor plugins that visualize indentation levels.
Where JSON and YAML Appear in Practice
The two formats have divided along distinct lines in the software industry.
JSON is the universal language of web APIs. REST APIs, webhooks, and browser-server communication use JSON because it is natively understood by JavaScript, broadly supported in every programming language, compact for transmission, and unambiguous about types. A JSON number is a JSON number. A JSON boolean is a JSON boolean. YAML uses implicit typing that can produce surprises: the value yes in YAML is interpreted as a boolean true by some parsers, and the value NO is interpreted as false. Country codes like NO (Norway) and keys like yes and no have caused real configuration bugs because YAML's implicit type inference made them into booleans.
YAML is the dominant format for configuration files that developers maintain over time. Docker Compose files are YAML. Kubernetes manifests are YAML. GitHub Actions workflow files are YAML. Ansible playbooks are YAML. Helm chart values files are YAML. The pattern is consistent: wherever a human needs to read and modify a file regularly, and where comments are useful for documenting intent, YAML is the preferred format.
TOML (Tom's Obvious, Minimal Language), published by Tom Preston-Werner in 2013, represents a third approach. TOML is designed to be unambiguous about types while remaining human-readable, and it does not use significant whitespace. Cargo configuration files for Rust, Python's pyproject.toml, and some other tools in the systems programming ecosystem use TOML as an alternative to both JSON and YAML. TOML has stricter type rules than YAML and more explicit syntax than either, making it less prone to the implicit-typing surprises that YAML can produce.
The Structural Equivalences
JSON and YAML share the same fundamental data model: objects (key-value maps), arrays (ordered sequences), and scalar values (strings, numbers, booleans, null). Every valid JSON document is also a valid YAML document, because YAML 1.2 explicitly includes JSON as a subset. The conversion from JSON to YAML is always lossless for data that uses standard types. The conversion from YAML to JSON may lose comments, since JSON has no comment syntax.
JSON's object notation uses curly braces with colon-separated key-value pairs: {"key": "value"}. YAML's block notation uses indentation: key: value on its own line. JSON's array notation uses square brackets with comma-separated items: ["one", "two"]. YAML's block notation uses dash prefixes: - one on one line, - two on the next.
JSON's string type always requires double quotes. YAML's scalar type inference handles most cases without quotes: unquoted values that look like numbers are numbers, values that look like booleans are booleans, and everything else is a string. When a value might be ambiguous, explicit string quoting is available in single or double quotes.
The conversion is mechanical: a parser reads the JSON, builds an in-memory data structure, and a YAML serializer writes that structure in YAML notation. No information about types is lost because both formats represent the same type system. The only content that changes is the punctuation syntax used to delimit the structure.
When to Convert in Each Direction
JSON to YAML conversion serves the maintenance direction. When a configuration file originally provided in JSON needs to be stored in a team repository and edited regularly, converting it to YAML makes ongoing maintenance easier. The converted file can be annotated with comments explaining why each setting has its value, reviewed in pull requests without attention to matching braces, and modified with less risk of punctuation errors.
YAML to JSON conversion serves the machine consumption direction. Some systems require JSON specifically, whether because they parse it with a JSON-only library or because they store configurations in a database. In those cases, the YAML file is the human-maintained source of truth, and the JSON is generated from it for the system's consumption. The YAML is read by humans, the JSON is read by machines, and the conversion provides the bridge between the two audiences.
Kubernetes is an example of the human-maintained YAML pattern: Kubernetes resource manifests are typically written and stored in YAML, including comments and documentation, but the Kubernetes API server internally works with JSON. The kubectl tool converts between them transparently. Developers write YAML, the system processes JSON, and the conversion happens automatically in the middle.
Conclusion
ToolHQ's JSON to YAML converter handles the conversion in both directions. Paste a JSON configuration and receive clean, indented YAML you can immediately annotate with comments. Paste a YAML configuration and receive valid JSON suitable for system consumption. The data content is identical; only the representation changes.
Frequently Asked Questions
Can YAML have comments but JSON cannot?
Correct. YAML supports comments starting with a hash character anywhere in the file. JSON has no comment syntax by specification. This is one of the main reasons teams prefer YAML for configuration files that need documentation.
Does converting JSON to YAML lose any data?
For standard data types, no. Numbers, strings, booleans, objects, and arrays all convert without data loss. The difference is purely syntactic. Some edge cases involving special characters may require quoting in YAML.
Why do APIs use JSON instead of YAML?
JSON is natively supported by JavaScript, is smaller in most cases, and has no whitespace-sensitivity. APIs prioritize machine readability and speed. YAML's human-readability features add no value when a program is the consumer.