YAML syntax reference for configuration and data files

Indentation defines YAML structure

Mappings use key-value pairs, while sequences use a hyphen for each item. Child content is indented consistently with spaces. Tabs are not portable indentation.

service:
        name: api
 ports:
  - 80

service:
  name: api
  ports:
    - 80

Mappings and sequences can be nested

Quote ambiguous scalar values

Plain scalars are convenient, but values that resemble booleans, nulls, dates, numbers, or punctuation-heavy strings may be interpreted by the parser.

Quote values when their exact string representation matters. Use block scalars for multi-line text.

version: 01
enabled: yes
date: 2026-07-19

version: "01"
enabled: true
date: "2026-07-19"

Use literal and folded block styles intentionally

The | style preserves line breaks, while > folds many line breaks into spaces. Chomping indicators can control the final newline.

Use block text for certificates, scripts, descriptions, and messages only when the destination expects the resulting newline behavior.

Use anchors and aliases sparingly

Anchors and aliases can reuse nodes, and merge behavior is supported by some YAML workflows. They reduce repetition but can make configuration harder to understand and do not map cleanly to every target format.

Avoid aliases from untrusted input with unsafe loaders. Use a safe parser configuration appropriate to the application.

Review YAML to JSON conversion

JSON supports only string object keys and a smaller set of scalar types. Comments, anchors, aliases, tags, and formatting choices do not survive ordinary conversion.

Validate the converted values, especially dates, large numbers, nulls, and quoted strings.

1. 1

   Parse with the target YAML version and safe schema.

2. 2

   Inspect inferred scalar types.

3. 3

   Resolve or remove aliases if required.

4. 4

   Convert to JSON.

5. 5

   Compare important values and structure.

6. 6

   Validate against a schema when available.