Plain unquoted string — most common
name: John Doe
Single-quoted: no variable or escape processing
path: '/usr/bin/node'
Double-quoted: supports escape sequences (\n, \t, etc.)
message: "Hello\nWorld"
Whole number (base 10)
port: 8080
Floating point number
threshold: 0.95
Boolean value — use only true/false (YAML 1.2)
debug: false
Null / absence of value
response: null
ISO 8601 date format
created: 2024-01-15T10:30:00Z
Single-line comment. No multi-line comment syntax.
# This is a comment key: value # inline comment
Force value to be treated as a specific type
port: !!str 8080 # string '8080' not int
Key-value pairs — indented block style
app: name: myapp port: 3000
Inline map — equivalent to block style
env: {NODE_ENV: prod, PORT: 8080}List of items — block style with dash+space
fruits: - apple - banana - cherry
Inline list — equivalent to block style
ports: [80, 443, 8080]
List where each item is a map
users:
- name: Alice
role: admin
- name: Bob
role: userArbitrarily deep nesting
database:
primary:
host: db1.example.com
port: 5432Merge the keys of a referenced mapping into current map
defaults: &defaults color: blue button: <<: *defaults text: Submit
Preserves newlines exactly as written
script: | #!/bin/bash echo "hello" exit 0
Newlines folded into spaces (great for long descriptions)
description: > This is a very long description that will be joined into one line.
Literal block, strip all trailing newlines
prompt: |- Enter value:
Literal block, keep all trailing newlines
template: |+ line1
Folded block, strip trailing newlines
message: >- This folds into one line no trailing newline
Assigns an anchor (label) to the current node
base: &base image: node:18 restart: always
References (copies) an anchored node
service1: <<: *base name: api service2: <<: *base name: worker
Anchor a scalar value to reuse it
read_timeout: &rto 30 write_timeout: *rto connect_timeout: *rto
Anchor a list
primary_colors: &colors - red - blue text_colors: *colors
Explicitly declare YAML version (optional, rarely needed)
%YAML 1.2 --- name: myapp
Marks the start of a YAML document. Required if using directives.
--- kind: Deployment --- kind: Service
Marks the end of a YAML document. Optional but useful.
--- debug: true ...
Multiple YAML docs in one file (stream)
Used in Kubernetes multi-resource files
Base64-encoded binary data
icon: !!binary | iVBORw0KGgo=
Indentation MUST use spaces only — never tabs
# WRONG: parent: \tchild: value # RIGHT: parent: child: value
Values containing ': ' (colon+space) must be quoted
# WRONG: url: http://example.com # RIGHT: url: "http://example.com"
1.0 parses as float! Quote or tag it to keep as string
version: '1.0' # string version: 1.0 # float
YAML 1.1 parses yes/no/on/off as booleans — quote to use strings
# YAML 1.1 (PyYAML): on: true # 'on' is boolean true! # Safe: always quote on: 'on'
Trailing spaces in keys are included in the key string
"key " (with space) != "key" — trim carefully
Duplicate keys — behavior is parser-specific (usually last wins). Treat as error.
Use a YAML linter to detect duplicate keys
| Функция | YAML | JSON |
|---|---|---|
| Комментарии | Yes: # comment | Не поддерживается |
| Требуются кавычки | Необязательны для строк | Обязательны для строк |
| Anchors/aliases | Yes: &anchor / *alias | Не поддерживается |
| Многострочные строки | Yes: | and > blocks | Escaped \n only |
| Табуляция для отступов | Только пробелы | Оба варианта |
| Является надмножеством JSON | Любой JSON является валидным YAML | - |
| Удобочитаемость | Очень высокая | Средняя |
| Доступность парсеров | Высокая | Очень высокая |
Важно: Многие парсеры YAML до сих пор используют YAML 1.1 по умолчанию (PyYAML Python, Psych Ruby в некоторых версиях).
YAML имеет два многострочных стиля:
Литеральный блок (|) — сохраняет переводы строк:
description: |
This is line one.
This is line two.
This is line four (after blank line).
Свёрнутый блок (>) — объединяет строки пробелами:
description: >
This is a long paragraph
that will be folded into
a single line.
Добавьте -, чтобы убрать завершающий перевод строки (|-, >-), или +, чтобы сохранить (|+, >+).
Один YAML-файл может содержать несколько документов, разделённых ---:
---
# Document 1: Config
apiVersion: v1
kind: ConfigMap
---
# Document 2: Service
apiVersion: v1
kind: Service
Это часто используется в манифестах Kubernetes.
Два пробела — наиболее распространённая конвенция, используемая в Kubernetes, Docker Compose, GitHub Actions и большинстве DevOps-инструментов. Некоторые проекты используют четыре пробела. Ключевое правило — единообразие в пределах файла: никогда не смешивайте уровни отступов.
Да, YAML поддерживает однострочные комментарии с помощью #. Синтаксис многострочных комментариев отсутствует. Комментарии удаляются при разборе и недоступны в загруженной структуре данных.
YAML является надмножеством JSON — любой валидный JSON является валидным YAML. YAML разработан для удобства чтения людьми с поддержкой комментариев, многострочных строк и якорей/псевдонимов. JSON более строгий, быстрее парсится и поддерживается повсеместно. Используйте YAML для файлов конфигурации и JSON для API и обмена данными.
В YAML 1.1 (используемом многими парсерами, включая PyYAML) 'on', 'off', 'yes', 'no' являются допустимыми булевыми значениями. Это может вызывать ошибки при использовании в качестве обычных строк (например, в Ansible). YAML 1.2 исправил это — только 'true' и 'false' являются булевыми. Решение: всегда заключайте эти значения в кавычки ('yes', 'no'), если хотите использовать их как строки.
Используйте литеральный блочный скаляр (|) для сохранения переносов строк: каждая строка в блоке становится реальным переносом в строке. Используйте складной блочный скаляр (>) для преобразования переносов в пробелы: отлично для длинных абзацев. Оба поддерживают необязательные chomping-индикаторы (- для удаления конечных переносов, + для сохранения всех).
YAML использует пробелы для отступов — никогда табуляцию. Все одноуровневые ключи должны быть на одном уровне отступа. Смешение табуляции и пробелов всегда вызывает ошибки. Распространённые исправления: включите в редакторе настройку 'заменять табуляции пробелами', используйте linter (yamllint), обеспечьте согласованную ширину отступа (2 или 4 пробела) по всему файлу.