Flow Style

Flow style is JSON-shaped YAML

Block style uses indentation. Flow style uses {} and [] on one line, and it is the reason every JSON document is also valid YAML.

block:
  a: 1
  b:
    - 2
    - 3

flow: {a: 1, b: [2, 3]}

Both halves parse to the same thing: {"a": 1, "b": [2, 3]}. Quotes on keys are optional in flow style, unlike JSON.

Syntax

The space after the colon is required. {a:1} does not parse as a mapping with a: 1, it parses as the single scalar a:1 inside a flow sequence context, and in a flow mapping it errors.

good: {a: 1}
bad: {a:1}      # -> {'bad': {'a:1': None}}, not what you meant

Multi-line flow

A flow collection may span lines. Indentation inside it is decoration, not structure, and the closing bracket just has to be more indented than the parent key.

allowed_origins: [
  "https://app.example.com",
  "https://admin.example.com",
]

resources: {
  limits: {cpu: "500m", memory: 512Mi},
  requests: {cpu: "100m", memory: 128Mi},
}

Comments still work inside a multi-line flow collection, which is the one thing this buys you over embedding raw JSON.

When flow style earns its place

- Short leaf values. ports: [80, 443] beats three lines of block style. - Empty collections. args: [] and env: {} have no block form. A bare args: is null, and a null is not an empty list to the consuming program. - Matrices and coordinate pairs. points: [[0, 0], [1, 1]] versus six lines. - Uniform rows. A list of two-field records reads better as a table:

routes:
  - {path: /health, method: GET,  auth: false}
  - {path: /users,  method: POST, auth: true}
  - {path: /users,  method: GET,  auth: true}

• Pasting JSON. A JSON blob from an API response drops in unchanged.

When it hurts

- Anything deep. {a: {b: {c: {d: 1}}}} is worse than four indented lines. - Long lines. Past ~80 characters a diff shows one changed line with no clue what changed inside it. - Block scalars are not allowed in flow style. You cannot write {msg: | and continue, so any multi-line string forces block style or the "a\nb" escape form.

# illegal
bad: {msg: |
  hello}

Mixing the two

You can nest flow inside block freely. You cannot nest block inside flow: once a { or [ is open, everything until its closing bracket is flow context.

# fine, flow inside block
service:
  name: api
  ports: [8080, 9090]
  labels: {app: api, tier: backend}

# not fine, block inside flow
service: {name: api, ports:
  - 8080}

The usual house style is block for structure, flow for the leaves. That keeps diffs one-concept-per-line while avoiding the four-line-per-two-numbers tax.