YAML pitfalls
Fix quoting, indentation, and value-type errors in block YAML.
Quote text when YAML could interpret it as structure or a different value type.
| Value | What can go wrong | Example |
|---|---|---|
| A comma inside an inline map | Starts another entry in { ... } | desc: "Retry, then alert" |
| A colon followed by a space | Can start a key/value pair | label: "Status: pending" |
| A hash at the start or after a space | Starts a comment | ref: "#request-flow" |
A leading YAML indicator such as *, &, or ! | Can be read as an alias, anchor, or tag | label: "* required" |
| A number used as text | Becomes a numeric value | version: "1.0" |
true, false, or null used as text | Becomes a boolean or null | label: "false" |
| An empty value | Becomes null | name: "" if an empty string is allowed |
1:N is a string in YAML 1.2; a colon without a following space does not
by itself start a key/value pair. yes and no are also strings under the
YAML 1.2 core schema. Quoting them is still useful when sharing data with
older parsers. See the YAML specification.
Prefer block style for longer entries
Inline maps work for short records. Use one field per line when entries get longer; commas in ordinary text then do not separate fields.
items:
- title: Phase 1
when: now
status: active
detail: A longer description with, commas, in it.In an inline map, quote that description:
items:
- { title: Phase 1, detail: "A longer description with, commas, in it." }Check indentation and types
Use spaces for indentation and align sibling fields. If a field requires a string, quote numeric or boolean-looking text. If it requires a number or boolean, leave the value unquoted.
After editing, run chiltepin check. Use the reported field path to find the
problem, then consult Validation or
chiltepin block <type> for the field's required type.