2026-08-27 · 8 min read
- yaml
- configuration
- ci
YAML scalars do not always retain the type their spelling suggests to a human. The active schema decides whether an unquoted token becomes a string, boolean, null, integer, float, or timestamp. Different platforms can parse the same file into different data.
YAML 1.1 schemas are especially known for treating yes, no, on, and off as booleans. YAML 1.2 core behavior is narrower, but libraries and CI products do not all use the same version or schema.
Learn which layer chooses the schema
The file itself may not fully determine parsing behavior. A CI service, Kubernetes library, static-site generator, or application framework can select a schema or add custom tags. Check the target platform rather than relying on a local editor preview.
- Identify parser library, version, and configured schema.
- Check whether keys undergo implicit typing as well as values.
- Test timestamps, leading-zero numbers, null spellings, and infinities.
- Avoid assuming a linter and runtime parse identically.
Quote values that are identifiers
Environment variables, matrix labels, version strings, account IDs, and feature names often need to remain strings. Quote ambiguous values at authoring time and keep actual booleans as explicit true or false.
Quoting every scalar mechanically is not always harmless: downstream schemas may require numbers or booleans. Use quotes to express the intended type, then validate the parsed structure against the consumer's schema.
Compare the representation consumers receive
Convert a minimal YAML fragment to JSON under each relevant parser. JSON's explicit strings and booleans make type differences easy to diff, although YAML comments, anchors, tags, and formatting do not survive the conversion.
- Keep an ambiguous-scalar fixture in parser compatibility tests.
- Validate the parsed object, not only YAML syntax.
- Review dependency upgrades for schema-default changes.
- Fail clearly when a field has the wrong type instead of coercing it.
Create a local debugging workflow
Use Flashman's YAML/JSON converter to expose common parsed shapes, JSON formatter to inspect nesting, diff tool to compare environments, case converter to review identifier conventions, and timestamp converter when date-like scalars are involved.
For authoritative behavior, run the target platform's parser in tests. Include yes, no, on, off, null, leading-zero values, and date-like tokens so a future library upgrade cannot silently rewrite the configuration contract.