Authoring
YAML pitfalls
Quote when in doubt — a few quoting rules that prevent most validation errors.
Most "schema errors" are really YAML quoting problems. The rule of thumb: when in doubt, quote the value. Quote whenever it contains:
| Character | What goes wrong unquoted | Fix |
|---|---|---|
, (comma) | Inside { a, b }, your sentence splits into several keys. | desc: "40 blocks, themes, agent skill" |
: (colon) | Read as key: value. 1:N becomes a number sequence. | card: "1:N" |
# (hash) | Everything after it becomes a comment. | label: "POST /orders #idempotent" |
Leading * & ! | > % @ ` | Special YAML characters. | Quote the whole value. |
Leading - plus a space | Looks like a list item. | Quote. |
Numbers (0, 02, 1e3) | Read as a number, fails text fields. | delta: "0", version: "1.0" |
yes / no / true / false / null | Read as booleans or null. | Quote. |
| Empty | Read as null. | name: "" |
Prefer block style for longer entries
Inline { key: value } is fine for short records. Past four or five fields,
switch to one field per line — it's easier to read, easier to diff, and has
no comma traps:
# ✓ Good — one field per line
items:
- title: Phase 1
when: now
status: active
detail: A longer description with, commas, in, it.
# ✗ Risky — inline style with unquoted commas
items:
- { title: Phase 1, when: now, status: active, detail: A longer description with, commas }The #1 mistake
Free-text fields — desc, note, summary, description — cause more
validation errors than everything else combined. Always quote them.
If avo check still complains, look the code up in
Validation — every code has a known fix.