YAML

YAML is structured data laid out as indented lines.

A label, a colon, a value. Nesting is spaces. Comments are allowed. That is why it shows up in CI, GitHub Actions, Docker Compose, and a pile of agent config — a human has to open the file at 1 a.m. and change one flag.

name: my-app
frontend: next
backend: hono

Spaces are the syntax

Line something up wrong, or mix tabs and spaces, and the file dies while still looking fine. When YAML "won't load," check the indent before you rewrite the pipeline. Quote strings that look like booleans. yes, on, and true have all betrayed a demo.

The CLI and your stack picker already made choices. The YAML you edit later should describe those choices, not invent a second stack. An agent that "just tweaks" two spaces can take Saturday with it.

When to refuse it

If two machines are the only readers, JSON is enough. If you are writing a schema that must not be misread, prefer a stricter format. YAML is for settings you touch. It is not a badge of sophistication.

Keep production secrets out of the YAML you commit. Point at the env file. The workflow file can name STRIPE_SECRET_KEY. It must not print the value. Judges will clone the repo. The Actions file goes with it.

What this unlocks

A config file stops looking like code you cannot touch.

Change the value. Respect the spaces. Leave the rest alone.