YAML Indentation and Types: Avoid Quiet Configuration Errors

YAML is designed to be pleasant to read, but its compact syntax makes a few characters carry a lot of meaning. A misplaced space can change a nested mapping into a sibling value, and an unquoted value can be interpreted differently than intended by the parser used in your project.

Indentation describes the structure

Use spaces consistently; tabs are not valid indentation in YAML. In this example, port belongs to database because it is indented beneath it.

database:
  host: localhost
  port: 5432
features:
  audit_log: true

If port begins at the left margin, it becomes a separate top-level field. This may not cause a parse error, but it can leave the program with a missing configuration value. Use a consistent indent width and review the rendered structure rather than relying only on how the text looks in an editor.

Quote values that must remain text

Values such as 00127, yes, dates and version-like strings can be interpreted differently across YAML versions and libraries. Quote a value when it must remain a string, especially for identifiers, codes and values passed unchanged to another system.

customer_id: "00127"
release: "2026-09-05"
enabled: true
timeout_seconds: 30

Here the identifier and release are explicitly text, while the boolean and timeout retain their intended types. The exact set of implicit conversions depends on the YAML specification and parser, so testing with the same library used in deployment matters.

Lists and mappings need different markers

A list item begins with a dash and a space. A mapping uses a colon. Nesting both is common in configuration, so it helps to keep each item small and align its children carefully.

services:
  - name: api
    replicas: 2
  - name: worker
    replicas: 1

Use YAML for the right job

YAML is a good fit for human-edited configuration. For machine-to-machine interchange, JSON's stricter and more explicit syntax may be easier to validate across systems. Keep one source of truth where possible; manually synchronized YAML and JSON files eventually drift apart.

Next steps

Inspect a non-sensitive YAML sample with the YAML to Python tool, then compare the formats in our YAML vs JSON guide. For formal behavior, consult the YAML specification and the documentation for the parser used by your project.