YAML style conventions

Contract

Enforces the yamllint-default style on every YAML document you write or normalize: 2-space indentation, lowercase true/false, plain unquoted scalars, block style, and a leading ---. Apply whenever the task is to author or clean up a .yaml/.yml file; not when picking what settings the file should contain.

Rules

1. Indentation — 2 spaces per level, spaces only. Each nesting level adds exactly two spaces. Never

use tabs, and never use 4 spaces. Sequence items under a key are indented two spaces from that key.

1. Booleans — lowercase true / false. A boolean scalar is always true or false. Never Yes,

No, On, Off, TRUE, False, y, or n — those are the legacy YAML 1.1 spellings this style rejects.

1. Quote only when required. Leave an ordinary scalar unquoted (name: api-gateway, count: 3).

Add quotes ONLY when the value would otherwise parse as a different type or is ambiguous:

• a string that reads as a boolean or number → quote it: answer: "yes", version: "3.10", zip: "07030".
• null, ~, or an empty value you want as a string → quote: note: "", tag: "null".
• a value beginning with an indicator character (@ % & ! ? | > # , {),

or containing : or a trailing space → quote it. When you must quote, prefer single quotes unless the value needs an escape.

1. Spacing — one space after : and after - . Write key: value, never key:value and never

key :value. A sequence dash is followed by one space: - item. No space before the colon.

1. No trailing whitespace; end with one newline. Strip spaces at end of line; the file ends in a single

\n.

1. Document start ---. Begin the file with a --- document-start marker on its own line. It is

required for a multi-document stream and is the linted default for single documents too.

1. Block style over flow. Write nested mappings and sequences in indented block form, one entry per

line. Do not collapse them into inline flow {key: value} / [a, b]. Reserve flow only for a genuinely empty collection (items: []).

1. Comments — # then text. A comment is a hash followed by one space. Put a full-line comment on its

own line, indented to the block it describes.

Worked examples

The base's echo-the-input default is on the left; the conforming YAML on the right.

A logging block handed in with tabs, Yes, and an inline flow map:

BEFORE  logging:
        	level: DEBUG
        	handlers: {console: Yes, file: No}

AFTER   ---
        logging:
          level: DEBUG
          handlers:
            console: true
            file: false

An HTTP server section indented four spaces, with over-quoted plain strings:

BEFORE  server:
            "host": "localhost"
            "port": "8080"

AFTER   server:
          host: localhost
          port: 8080

A value that genuinely needs quoting because it would parse as a boolean or a float:

BEFORE  reply: yes
        release: 2.0

AFTER   reply: "yes"
        release: "2.0"

Edge cases & exceptions

• A string that looks like a number (a leading-zero code, a version, a phone number) → quote it so it

stays a string: code: "007", not code: 007.

• A value containing a colon-space (title: a: b) parses wrong unquoted → quote the whole value:

title: "a: b".

• An empty mapping or list is the one place flow is fine: env: {} / args: [].
• A multi-line string uses a block scalar (| literal or > folded), still indented two spaces under

its key — not a quoted one-liner with \n.

• Anchors/aliases (&name / *name) keep their leading indicator; they are not quoted.

Do / Don't

• Do write booleans as true / false. Don't use Yes / No / On / Off.
• Do indent with 2 spaces. Don't use tabs or 4 spaces.
• Do leave plain scalars unquoted. Don't wrap every string in quotes.
• Do quote a value that would otherwise parse as a bool/number/null. Don't leave port: "8080" quoted when

the value is a plain integer.

• Do use block style for nested maps. Don't inline them as {a: 1, b: 2}.
• Do begin the file with ---. Don't start straight into the first key.
• Do put one space after :. Don't write key:value.

Common mistakes

• Carrying the input's 4-space or tab indentation straight into the output.
• Preserving Yes / No / On / Off instead of normalizing to true / false.
• Quoting ordinary strings ("localhost", "api") that never needed quotes.
• Forgetting to quote a value that DOES parse wrong (version: 1.0 silently becomes a float 1).
• Emitting a nested map as inline flow { } instead of an indented block.
• Omitting the leading ---.
• key:value with no space after the colon.

Quick checklist

• ] Two-space indentation, no tabs, no 4-space blocks.
• ] Every boolean is true or false, never Yes/No/On/Off.
• ] Plain scalars unquoted; only ambiguous values quoted.
• ] One space after each : and each - .
• ] Nested collections in block style, not inline flow.
• ] File opens with ---; no trailing whitespace.