Authoring
YAML pitfalls
Quote when in doubt — the handful of YAML quoting rules that prevent most validation errors.
The YAML parser is doing exactly what you asked. Most "schema errors" are actually YAML mis-parses. Quote the value whenever it contains:
| Character | What goes wrong unquoted | Fix |
|---|---|---|
, (comma) | Inside { a, b } flow style, treated as a separator. Your sentence becomes 3 keys. | desc: "40 blocks, themes, agent skill" |
: (colon) | Treated as key: value. 1:N becomes a number sequence. | card: "1:N" |
# (hash) | Treated as a comment from there on. | label: "POST /orders #idempotent" |
Leading * & ! | > % @ ` | YAML anchor / tag / literal / fold / reserved characters. | Quote the whole value. |
Leading - followed by space | Looks like a list item. | Quote. |
Numeric-looking (0, 02, 1e3) | Parsed as a number, fails string schemas. | Quote: delta: "0", version: "1.0" |
yes / no / true / false / null | YAML 1.1 booleans (still around in some parsers). | Quote. |
| Empty | Parsed as null. | Quote: name: "" |
Flow style vs block style
Inline-mapping { k: v } is fine for short records (under ~5 fields). For
anything longer, use block-style — easier diffs, fewer comma traps:
# ✓ Good — block style for longer records
items:
- title: Phase 1
when: now
status: active
detail: A longer description with, commas, in, it.
# ✗ Bad — flow-style with unquoted commas
items:
- { title: Phase 1, when: now, status: active, detail: A longer description with, commas }The #1 source of validation errors
When you write a desc / note / summary / description that contains
prose, always quote it — those fields are the number-one source of
validation errors.
When avo check still complains, look up the code in
Validation — every diagnostic has a mechanical
fix.