JSON vs YAML for Config Files: Which Should You Use?

• Comments. A config file is documentation for whoever edits it next, and JSON has no place for that.
• Less punctuation. No braces, fewer quotes, no commas to forget, so diffs are smaller and easier to review.
• Readable long text. Multi-line strings such as scripts or certificates can be written as blocks instead of one line full of \n.

Indentation mistakes change the data silently

In JSON a misplaced brace is a syntax error. In YAML a missing indent is usually valid, just different. Here enabled was meant to sit under tls:

server:
  host: localhost
  port: 8080
tls:
enabled: true

It parses without error to {"server": {...}, "tls": null, "enabled": true}. TLS is now off, and nothing complained.

Unquoted values pick their own type

YAML guesses the type of every unquoted value. version: 1.10 is read as the number 1.1, so the version silently changes. And parsers that follow the older YAML 1.1 rules read country: no as false. With the yaml package's default YAML 1.2 rules it stays the string no, but switched to version 1.1 the same file returns false. A file can therefore mean different things to two programs that both say they read YAML.

Comments do not survive a program

Comments are the main reason to choose YAML, and most code that reads and writes a config file throws them away. Parsing to plain data and writing it back loses every comment. The yaml package can keep them, but only if you work with its document API (YAML.parseDocument and doc.toString()) instead of plain objects.

Never build YAML by joining strings. Use a library, and check how it quotes ambiguous values:

import { dump } from "js-yaml";

dump({ country: "no", version: "1.10", zip: "007", note: "a: b" });
// country: 'no'
// version: '1.10'
// zip: '007'
// note: 'a: b'

js-yaml quotes all four, so any reader gets strings back. The yaml package's YAML.stringify quotes 1.10, 007 and a: b but writes country: no without quotes, which is correct for YAML 1.2 readers and wrong for YAML 1.1 readers. If the file goes to tools you do not control, prefer output that quotes such values. Note that js-yaml 5 has no default export, so use the named import shown above.

• Use JSON when programs write the file or several languages read it. Every parser agrees on what it means.
• Use YAML when people edit the file often and comments matter, and the tools that read it already expect YAML.
• With YAML, quote strings that look like numbers, booleans or dates, and validate the parsed result against a schema in CI, so an indentation slip fails a build instead of a deployment.
• Do not hand-edit generated YAML. Change the source and regenerate, or the next generation overwrites the edit.