YAML Syntax Rules You Must Know
YAML looks informal, but underneath it follows a fairly small set of strict rules. Once these actually click, most YAML files stop looking like a wall of unpredictable whitespace and start looking like, well, rules being followed consistently.
1. Indentation defines structure
Spaces — never tabs — control nesting. Two keys at the same level of meaning need to start at exactly the same column:
server:
host: localhost
port: 8080host and port both belong to server because they're indented the same amount. Get that indentation even slightly inconsistent and the parser either errors out or, worse, silently attaches a key to the wrong parent.
2. A colon-space separates key and value
key: value needs the space after the colon. key:value without a space is read as a single string, not a key-value pair, which is a surprisingly common typo.
3. A dash-space starts a list item
fruits:
- apple
- bananaSame rule — the space after the dash matters, and every item in the list needs to line up at the same indentation.
4. Quotes are optional, until they're not
Most plain strings don't need quotes. But you do need them when a value could be misread as something else: a number-looking string like "007", a value with a colon like "10:30", or a string that starts with a special character like * or &.
5. Three dashes can start a document
--- on its own line marks the start of a YAML document, and is required if you're putting multiple documents in one file, separated by more --- lines. For a single simple config file you'll often see it omitted entirely, which is also valid.
6. Booleans and null have several spellings
true/false, yes/no, and ~ or null for a null value are all recognized by most parsers, though sticking to true/false/null is the safer, more portable habit. We go deeper on this in YAML data types explained.
If you'd rather just see whether your file follows these rules than memorize all of them, paste it into the validator — it'll tell you the exact line if something's off.