Skip to content

YAML Шпаргалка

Дружественный к человеку стандарт сериализации данных для конфигурационных файлов.

01

Начало работы

Базовая структура

YAML использует отступы (пробелы, не табы) для вложенности. Отображения используют key: value, последовательности — - item. Inline-синтаксис использует [] для списков и {} для отображений. Комментарии начинаются с #.

yaml
# YAML uses indentation for structure
# Comments start with #

# Key-value pairs (mappings)
name: Alice
age: 30

# Nested mappings (use consistent indentation)
person:
  name: Bob
  age: 25
  address:
    city: NYC
    zip: 10001

# Sequences (lists)
hobbies:
  - reading
  - coding
  - music

# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}

Комментарии

Комментарии начинаются с # и должны иметь перед собой пробел или начало строки. Внутри блочных скаляров (| и >) # — литеральный контент, а не комментарий. Многострочного синтаксиса комментариев нет: каждой строке нужен свой #.

yaml
# Full-line comment
key: value  # Inline comment (whitespace before # required)

# Comments can appear anywhere
# - before documents
# - inside sequences
list:
  - a  # first item
  - b  # second item

# Block scalar headers DO accept comments
text: |  # literal block
  line one

# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
  # this is part of the string, not a comment

Правила отступов

YAML строго запрещает табы для отступов — допускаются только пробелы. Отступы должны быть согласованы в пределах уровня, но не обязаны иметь фиксированное число. Символ - в последовательностях является частью отступа. Смешивание табов и пробелов вызывает ошибку парсера.

yaml
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention

mapping:
  nested:
    deeply_nested: value

# Sequences can be indented at the same level as the key
items:
  - one
  - two

# Or indented further (both are valid)
items2:
    - one
    - two

# WRONG: tab characters cause parser errors
# bad:	value   (tab before value)

# Hyphen counts as indentation start
- item1
- item2

Начало и конец документа

--- отмечает начало YAML-документа; ... отмечает конец. Файл может содержать несколько документов, разделённых --- (поток документов). Для конфигов с одним документом ведущий --- необязателен, но рекомендуется как подсказка парсерам.

yaml
# --- separates documents in a stream
# ... ends a document (optional)

---
name: first document
value: 1
...
---
name: second document
value: 2
...

# A single document needs no markers
key: value

# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMap

Частые ловушки

Двоеточию нужен следующий пробел, чтобы быть разделителем отображения. YAML 1.1 и 1.2 различаются в yes/no/on/off (boolean в 1.1, строки в 1.2) и в восьмеричных литералах. Пустые значения — null, отличные от пустых строк. Многие парсеры (PyYAML) до сих пор следуют правилам 1.1.

yaml
# Colon needs a space after it
key:value      # WRONG: parsed as a single string "key:value"
key: value     # correct

# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes    # YAML 1.1: true; YAML 1.2: "yes" string

# Numbers with leading zeros
version: 010   # YAML 1.1: octal 8; YAML 1.2: string "010"

# Unquoted strings with special chars
url: example.com/path   # OK
url: example.com:8080   # WRONG: parsed as mapping with key example.com

# Empty values
empty:       # null
empty2: ~    # explicit null
empty3: ""   # empty string (different from null)

YAML и JSON

YAML 1.2 спроектирован так, что JSON — строгое подмножество: любой JSON-файл является валидным YAML. YAML добавляет комментарии, блочную структуру, якоря, многострочные строки и теги. JSON требует кавычек для всех ключей и строковых значений, YAML это ослабляет для простых скаляров.

yaml
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML

# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# Equivalent YAML:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents

# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)

# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.
02

Скаляры (строки, числа, boolean, null)

Простые и закавыченные строки

Простые строки не нуждаются в кавычках, если не выглядят как числа, boolean, null или даты. Одинарные кавычки экранируют ' только удвоением (''); других escape-последовательностей нет. Двойные кавычки поддерживают полные escape-последовательности (\n, \t, \uXXXX). Кавычки принудительно задают строковый тип.

yaml
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com

# Single-quoted — escape ' by doubling
msg: 'it''s fine'

# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1"   # Greek alpha
tab: "col1\tcol2"

# Multi-word plain strings are fine
description: This is a plain string with spaces

# Strings that look like other types must be quoted
version: "1.0"      # string, not float
notBool: "true"     # string, not boolean
notNull: "null"     # string, not null
date: "2024-01-01"  # string, not date

Числа

YAML 1.2 использует 0o для восьмеричных (YAML 1.1 использовал просто ведущий 0). Подчёркивания в числах допускаются для читаемости. .inf и .nan — специальные литералы float. Закавычивайте любое значение, которое должно быть строкой, но выглядит числом (версии, телефоны, ID).

yaml
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000   # readable grouping (YAML 1.2)

# Octal & hex (YAML 1.2 prefixes)
octal: 0o17     # = 15 decimal
hex: 0xFF       # = 255 decimal
binary: 0b1010  # = 10 decimal

# Floats
pi: 3.14159
exp: 1.0e+3     # 1000.0
neg_exp: -2.5e-4

# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan

# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"

Boolean

YAML 1.2 сузил boolean до true/false (и True/False, TRUE/FALSE). YAML 1.1 (используется PyYAML) трактует yes/no/on/off/y/n как boolean — знаменитый источник багов (например, норвежское 'no' превращается в false). Всегда закавычивайте эти строки, если имеете их в виду буквально.

yaml
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false

# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1

# To force a string:
answer: "yes"      # always a string
option: "on"
flag: "y"

# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!

# Safe practice: quote if you mean the literal string
country: "no"   # Norway country code, not False

Null-значения

YAML принимает null, Null, NULL, ~ и пустое значение как null. Пустое значение (ключ без ничего после двоеточия) — null, отличное от пустой строки "". Парсеры отображают YAML null в null-значение языка хоста (None, null, nil).

yaml
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5:             # empty value

# Distinguish null from empty string
empty_string: ""
null_value: null

# In sequences
list:
  - value
  - null         # explicit null item
  - another

# In nested structures
config:
  timeout: null   # explicitly unset
  retries: 3

# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nil

Даты и отметки времени

Даты и отметки времени ISO 8601 распознаются большинством парсеров как нативные типы. Голый YYYY-MM-DD становится датой; со временем — datetime. Закавычьте значение, чтобы оставить его строкой. Обозначения часового пояса (Z, +08:00) поддерживаются.

yaml
# Date (ISO 8601)
date: 2024-01-15

# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00

# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'

# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)

Вывод типов

Система типов YAML разрешает незакавыченные скаляры через схему. Схема Failsafe трактует всё как строки; схемы JSON и Core выводят int, float, bool, null, date. Используйте кавычки или явные теги (!!str, !!int), чтобы переопределить разрешение, когда нужно.

yaml
# YAML infers types from unquoted scalars
str: hello             # string
int: 42                # integer
float: 3.14            # float
bool: true             # boolean
null_val: null         # null
date: 2024-01-01       # date
list: [1, 2, 3]        # sequence

# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"

# Or with the !!str tag
forced: !!str 42        # string "42"
forced_int: !!int "42"  # integer 42

# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferred
03

Отображения

Простое отображение

Отображение — пары key: value, где ключи обычно строки. Ключи могут быть любым скаляром (число, bool, даже null). Дубликаты ключей не рекомендуются, и поведение зависит от парсера (часто побеждает последний). Используйте линтер, чтобы ловить случайные дубликаты.

yaml
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]

# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key

# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second   # overrides "first" in many parsers

# Values can be any type
mixed:
  string: text
  number: 42
  list: [1, 2, 3]
  nested:
    deep: value

Вложенные отображения

Вложенные отображения создаются отступом дочерних ключей. Отступы должны быть согласованы в пределах уровня. Фиксированного размера отступа нет, но 2 пробела — де-факто стандарт. Более глубокая вложенность снижает читаемость — рассмотрите выпрямление очень глубоких структур.

yaml
# Nest mappings with consistent indentation
server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    cert: /etc/ssl/cert.pem
    key: /etc/ssl/key.pem

database:
  primary:
    host: db1.example.com
    port: 5432
  replica:
    host: db2.example.com
    port: 5432

# Indentation level is up to you — just be consistent
# 2 spaces is the most common convention

Отображение последовательностей

Отображения и последовательности свободно компонуются. Частый паттерн — последовательность отображений (список записей), где каждый - начинает элемент, а выровненные ключи принадлежат этому элементу. Отступ последующих ключей должен совпадать с первым ключом после -.

yaml
# Values in a mapping can be sequences
servers:
  - web1.example.com
  - web2.example.com
  - web3.example.com

# Sequence of mappings (very common)
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# Each - starts a new item; aligned keys form one mapping
services:
  - name: api
    port: 8080
    env:
      - dev
      - prod
  - name: web
    port: 3000

# Mixed: mapping containing sequence containing mapping
config:
  endpoints:
    - path: /health
      method: GET
    - path: /users
      method: POST

Сложные ключи

YAML допускает любой скаляр или коллекцию как ключ через индикатор ? key. Это редкость в конфигах, но полезно для таблиц поиска (например, цены по региону и типу инстанса). Сложные ключи неудобно читать — большинство конфигов ограничивается простыми строковыми ключами.

yaml
# Keys can be complex objects using ? notation
? key1
: value1

# A mapping as a key
? host: localhost
  port: 8080
: connection1

# A sequence as a key
? [a, b, c]
: indexed_value

# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023

# In flow style:
{[a, b]: value, {x: 1}: other}

# Most config files just use plain string keys
simple: value

Inline (flow) отображения

Flow-стиль использует {} для отображений и [] для последовательностей, похоже на JSON. Полезен для коротких компактных данных в одну строку. В отличие от JSON, YAML не допускает висячих запятых. Смешивайте flow и block свободно, но в конфигах предпочитайте block ради читаемости.

yaml
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Mixed flow and block
block_key:
  flow_value: {x: 1, y: 2}
  another: value

# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}

# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}

# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,}   # parse error

Порядок ключей и стиль

Сам YAML по спецификации сохраняет порядок отображения, но объекты языков хоста могут не сохранять (хотя большинство современных словарей сохраняют). Для читаемости конфига группируйте связанные ключи, используйте единый стиль имён (snake_case или camelCase) и добавляйте комментарии для разделения секций.

yaml
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered

# Consistent key style improves readability
config:
  server:
    host: localhost      # snake_case
    port: 8080
    max_connections: 100
  database:
    host: db.example.com
    port: 5432
    connection_pool: 10

# Group related keys together
# Use comments to delineate sections
app:
  # networking
  host: 0.0.0.0
  port: 3000
  # limits
  timeout: 30
  retries: 3
04

Последовательности

Блочные последовательности

Блочные последовательности используют - (дефис и пробел) перед каждым элементом. Элементы могут быть любого типа: скаляры, отображения, вложенные последовательности. - считается частью отступа, поэтому последующие ключи в элементе-отображении выравниваются с первым ключом после дефиса.

yaml
# A sequence (list) uses - followed by space
fruits:
  - apple
  - banana
  - cherry

# Sequence as top-level document
- item1
- item2
- item3

# Empty sequence
empty: []
or_with_marker: []

# Sequence with mixed types
mixed:
  - string
  - 42
  - true
  - null
  - key: value   # a mapping as an item

Вложенные последовательности

Вложенные последовательности образуются дальнейшим отступом уровней -. Их становится трудно читать после 2 уровней — переходите на flow-стиль для внутренних последовательностей. Древовидные структуры (последовательность отображений с children) читаются лучше, чем чисто вложенные последовательности.

yaml
# Sequence of sequences
matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

# More readable with flow style for inner
matrix2:
  - [1, 2, 3]
  - [4, 5, 6]

# Deeply nested
tree:
  - name: root
    children:
      - name: child1
        children:
          - name: grandchild1
      - name: child2

# 3D: sequence of sequence of sequence
cube:
  - - [1, 2]
    - [3, 4]
  - - [5, 6]
    - [7, 8]]

Последовательность отображений

Последовательность отображений — самый частый паттерн YAML (списки записей). Каждый - начинает новый элемент; последующие ключи на том же отступе принадлежат этому элементу. Выравнивайте ключи после - для читаемости. Пустой элемент-отображение записывается как {}.

yaml
# Most common pattern: list of records
users:
  - name: Alice
    email: [email protected]
    roles:
      - admin
      - user
  - name: Bob
    email: [email protected]
    roles:
      - user

# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
  - host: web1.example.com
    port: 8080
    healthy: true
  - host: web2.example.com
    port: 8080
    healthy: false

# Empty mapping item
list:
  - {}
  - name: real

Inline (flow) последовательности

Flow-последовательности используют [] и эквивалентны блочным. Полезны для коротких списков в одну строку. Flow-последовательности могут занимать несколько строк ради читаемости. В отличие от JSON, YAML запрещает висячие запятые. Смешивайте flow-последовательности с блочными отображениями свободно.

yaml
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Mixed: block mapping with flow sequence value
config:
  ports: [80, 443, 8080]
  hosts: [web1, web2, web3]

# Spread across multiple lines (still flow style)
long_list: [
  item1,
  item2,
  item3
]

# NO trailing comma allowed
bad: [1, 2, 3,]   # error

Смешанный и разнородный контент

YAML допускает совершенно разнородный контент в последовательностях и отображениях: любой элемент может быть любого типа. Эта гибкость мощна, но означает, что приложение должно валидировать структуру. Используйте схему (JSON Schema, Cue и т. д.) для строгой валидации.

yaml
# Sequences can mix types freely
mixed:
  - string
  - 42
  - true
  - null
  - [1, 2, 3]            # nested sequence
  - key: value           # mapping
    another: value2
  - - nested
    - sequence

# Heterogeneous mapping values
config:
  string_val: text
  int_val: 42
  list_val: [a, b, c]
  map_val: {x: 1, y: 2}
  null_val: null
  bool_val: true

# YAML has no schema enforcing uniformity —
# the application must validate structure

Паттерны отступов последовательностей

Последовательности под ключом могут быть с отступом (паттерн 1) или на том же уровне (паттерн 2, так как - считается отступом). Оба варианта валидны; выберите один и будьте последовательны. В последовательностях отображений все ключи элемента должны выравниваться с первым ключом после -.

yaml
# Pattern 1: sequence indented under key
items:
  - a
  - b

# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b

# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).

# Mapping item alignment — both keys align with first
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# WRONG: misaligned keys cause parse errors
# users:
#   - name: Alice
#    age: 30    # one space off — error
05

Многострочные строки (folded и literal)

Литеральный блочный скаляр (|)

Литеральный блочный скаляр | сохраняет каждый перевод строки точно как написан. Отступ (величина после |) снимается с каждой строки. Chomping по умолчанию (clip) сохраняет один хвостовой перевод строки. Используется для скриптов, кода, поэзии, ASCII-арта — везде, где важны литеральные переводы строк.

yaml
# | preserves newlines as-is
script: |
  #!/bin/bash
  echo "Hello"
  echo "World"

# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n

poem: |
  Roses are red,
  Violets are blue,
  YAML is clean,
  And JSON is too.

# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlines

Свёрнутый блочный скаляр (>)

Свёрнутый блочный скаляр > превращает одиночные переводы строк в пробелы, соединяя строки в абзацы. Пустые строки становятся литеральными переводами строк. Строки с большим отступом, чем контент блока, сохраняются буквально (полезно для примеров кода внутри прозы).

yaml
# > folds newlines into spaces (paragraphs)
description: >
  This is a long paragraph that
  spans multiple lines in the YAML
  but will be joined into one line
  when parsed.

# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"

# Blank lines preserve a newline
paragraphs: >
  First paragraph here.

  Second paragraph here.

  Third paragraph here.

# More indented lines are preserved literally
example: >
  This is folded.
    This line is more indented — kept literal.

Индикаторы chomping (+/-)

Chomping управляет хвостовыми переводами строк: clip (по умолчанию, без индикатора) сохраняет один; strip (-) удаляет все; keep (+) сохраняет все. Индикатор ставится сразу после | или > (например, |-, |+, >-, >+). Strip полезен для строк, используемых inline; keep редок, но точно повторяет исходник.

yaml
# Default (clip): single trailing newline
text: |
  line1
  line2
# Result: "line1\nline2\n"

# Strip (-): remove ALL trailing newlines
text_strip: |-
  line1
  line2
# Result: "line1\nline2"

# Keep (+): keep ALL trailing newlines
text_keep: |+
  line1
  line2


# Result: "line1\nline2\n\n\n"

# Same applies to folded scalars
folded_keep: >+
  folded
  text

Индикатор отступа

Когда контент блочного скаляра начинается с пробелов, нужно явно указать отступ контента цифрой (например, |2). Цифра показывает, сколько пробелов отступа относится к структуре, а сколько — к контенту. Комбинируйте с chomping: |2-, >4+ и т. д. Нужно редко, но когда нужно — обязательно.

yaml
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly

# Without indicator (ambiguous):
# content:
#   indented_line   # is the leading space content or not?

# With explicit indentation indicator (digit after | or >)
literal: |2
    hello
      world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra

# Combined with chomping (order: indent then chomp)
text: |2-
    no trailing newline

# Folded with explicit indent
folded: >4
    paragraph with
    explicit indent

# Most of the time you don't need this — only when
# content legitimately starts with spaces

Простые многострочные строки

Простые и закавыченные скаляры могут занимать несколько строк, а переводы строк складываются в пробелы (похоже на >, но неявно). Это хрупко, потому что разрывы строк зависят от контекста и спецсимволов. Для любого нетривиального многострочного текста предпочитайте явные блочные скаляры | (literal) или > (folded).

yaml
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
  a long message
  on multiple lines
# Result: "this is a long message on multiple lines"

# Quotes are required if the string contains special chars
quoted: "this is also
  a long message
  on multiple lines"
# Result: "this is also a long message on multiple lines"

# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons

# Plain is fragile for multi-line — prefer | or >
safe_literal: |
  Use literal block for
  predictable multi-line text

Выбор fold или literal

Правило: используйте |, когда переводы строк значимы (скрипты, конфиги, код), и >, когда нужен читаемый многострочный исходник, но соединённый абзац (описания, документация). Используйте |-, чтобы срезать хвостовой перевод строки, когда строка используется inline.

yaml
# Use | (literal) when newlines matter:
script: |
  #!/bin/bash
  set -e
  echo "Step 1"
  echo "Step 2"

config_file: |
  [default]
  region=us-east-1
  output=json

# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
  This service handles user authentication
  and session management. It talks to the
  PostgreSQL database and Redis cache.

# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
  echo hello

# Use plain single-line for short strings
short: hello world
06

Якоря и алиасы

Определение якорей (&)

&name определяет якорь на узле (отображении, последовательности или скаляре). Якорь не меняет значение в этом месте — он просто помечает узел для переиспользования. Алиасы (*name) ссылаются на узел по имени. Якоря должны быть определены до использования в документе.

yaml
# &name defines an anchor on a node
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
  database: *defaults
  # *defaults is an alias — references the anchored node

# Anchors on scalars
version: &ver "1.0.0"
current: *ver

# Anchors on sequences
colors: &colors
  - red
  - green
  - blue
primary: *colors

Использование алиасов (*)

*name — алиас, ссылающийся на ранее помеченный якорем узел. Алиасы делят идентичность с оригиналом (тот же объект в большинстве парсеров). Якоря и алиасы ограничены документом — они не могут ссылаться через границы документов ---. Комбинируйте с << (merge key), чтобы наслаивать переопределения.

yaml
# Define once, reuse by alias
base: &base
  image: nginx:1.25
  restart: always

web:
  <<: *base
  ports:
    - "80:80"

api:
  <<: *base
  ports:
    - "8080:8080"
  environment:
    - DEBUG=true

# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)

# Aliases can't span documents
# Each document has its own anchor namespace

Область видимости якорей

Якоря ограничены своим документом и должны быть определены до любых ссылок-алиасов (никаких прямых ссылок вперёд). Несколько алиасов могут ссылаться на один якорь. Алиас на алиас работает: разрешается транзитивно. Ссылки между документами — ошибка.

yaml
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
  key: value
use: *shared   # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared   # ERROR: unknown anchor

# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later      # ERROR
later: &later value

# Multiple aliases to the same anchor are fine
template: &tpl
  timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl

# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b   # resolves to "value"

Переопределение значений с якорем

Алиас (*name) заменяет узел целиком — частично переопределить его нельзя. Чтобы переопределить отдельные ключи помеченного отображения, используйте merge key <<, чтобы слить отображение с якорем, затем добавить или переопределить ключи. Это канонический паттерн композиции конфигурации.

yaml
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  log_level: warn      # override
  host: prod.example.com   # add

# Result:
# production:
#   timeout: 30
#   retries: 3
#   log_level: warn
#   host: prod.example.com

# Without <<, an alias replaces the whole node:
wrong:
  thing: *defaults
  # thing is the FULL defaults mapping — can't override

Якоря в последовательностях

Якоря могут помечать целые последовательности, отдельные элементы последовательности или отображения внутри последовательности. Паттерн слияния << особенно полезен в последовательностях похожих записей (например, определения сервисов), чтобы делить общие поля. Помечайте отдельные элементы через - &name value.

yaml
# Anchors work on sequence items too
common: &common
  enabled: true
  log: stdout

services:
  - name: web
    <<: *common
    port: 80
  - name: api
    <<: *common
    port: 8080
  - name: worker
    <<: *common
    queue: jobs

# Anchoring a whole sequence
endpoints: &endpoints
  - /health
  - /metrics
  - /ready

monitoring:
  checks: *endpoints

# Anchoring individual sequence items
list:
  - &first one
  - two
  - *first   # "one" again

Оговорки по якорям

У якорей есть оговорки: алиасы делят идентичность (мутация одного влияет на все ссылки в мутабельных парсерах), они добавляют когнитивную нагрузку, а большинство сериализаторов (включая вывод JSON) разворачивают их в обычные копии. Используйте якоря для настоящего переиспользования (шаблоны, значения по умолчанию), а не для микрооптимизации.

yaml
# Caveat 1: shared identity can surprise you
defaults: &defaults
  list: [1, 2, 3]

a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.

# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.

# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.

# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).

# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x   # ERROR

# Prefer anchors for genuine reuse, not micro-optimization.
07

Merge keys (<<)

Базовое слияние (<<)

Merge key << берёт отображение (обычно алиас) и сливает его пары ключ-значение в текущее отображение. Ключи, явно заданные в текущем отображении, переопределяют слитые. Это канонический паттерн наследования конфигурации в YAML.

yaml
# << merges a referenced mapping into the current one
defaults: &defaults
  adapter: postgres
  pool: 5
  timeout: 5000

development:
  <<: *defaults
  database: myapp_dev
  host: localhost

production:
  <<: *defaults
  database: myapp_prod
  host: db.example.com
  pool: 20      # override

# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhost

Несколько слияний

<< может сливать несколько отображений, если передать flow-последовательность алиасов ([*a, *b, *c]). Слияния применяются слева направо; более поздние переопределяют ранние для дублирующихся ключей. Явные ключи в отображении всегда побеждают любой слитый ключ. Несколько записей << тоже разрешены.

yaml
# << can merge multiple mappings (sequence value)
base: &base
  logging: info
  retries: 3

security: &security
  auth: required
  tls: true

service: &service
  port: 8080
  host: 0.0.0.0

# Merge multiple in one go
production:
  <<: [*base, *security, *service]
  environment: prod
  port: 80        # override service.port

# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.

# You can also have multiple << entries:
combined:
  <<: *base
  <<: *security
  custom: value

Переопределение и приоритет

Приоритет слияния: явные ключи в отображении всегда побеждают. Среди слитых отображений более поздние в последовательности переопределяют ранние для одного ключа. Используйте это, чтобы чисто наслаивать переопределения: значения по умолчанию, затем ролевые, затем специфичные для инстанса.

yaml
# Explicit keys override merged keys
template: &template
  port: 8080
  log: info
  timeout: 30

instance:
  <<: *template
  port: 9090        # overrides template.port
  log: debug        # overrides template.log
  host: example.com # added

# Final: {port: 9090, log: debug, timeout: 30, host: example.com}

# Precedence: explicit > later merge > earlier merge
a: &a
  k: from_a
  x: 1
b: &b
  k: from_b
  y: 2

result:
  <<: [*a, *b]
  k: explicit   # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}

Паттерн слияния с якорями

Паттерн merge и anchor — хлеб Docker Compose и похожих конфигов: определите якорь defaults, затем каждый сервис сливает его и переопределяет отдельные поля. Это держит конфиги DRY, не жертвуя настройкой каждого сервиса.

yaml
# Common pattern: anchor templates, merge + override
defaults: &defaults
  image: nginx:1.25
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *defaults
    ports: ["80:80"]
  api:
    <<: *defaults
    image: node:20      # override
    ports: ["8080:8080"]
    environment:
      NODE_ENV: production
  worker:
    <<: *defaults
    image: worker:latest
    command: ["./run.sh"]

# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.

Ограничения merge

Merge key << работает только для отображений — последовательности и скаляры сливать нельзя. Слияние поверхностное: вложенное отображение в текущем узле ЗАМЕНЯЕТ слитое целиком (без глубокого слияния). Для глубокого слияния перестройте данные или делайте это в коде приложения.

yaml
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]

# This does NOT merge list items:
combined:
  <<: *list      # WRONG: *list is a sequence, not a mapping
  extra: value   # parse error or unexpected behavior

# Deep merge is NOT supported
parent: &parent
  nested:
    a: 1
    b: 2

child:
  <<: *parent
  nested:
    c: 3   # REPLACES parent.nested entirely
# Result: {nested: {c: 3}}  — NOT {nested: {a:1, b:2, c:3}}

# To deep-merge, you must do it in application code
# or restructure the data.

Статус и устаревание merge key

Merge key << был расширением YAML 1.1, удалённым из ядра спецификации YAML 1.2. На практике большинство парсеров его поддерживает (PyYAML, js-yaml, ruamel, SnakeYAML), но строгие парсеры 1.2 его отвергают. Используйте сегодня, но помните, что это нестандартно; для новых форматов рассмотрите конфигурационные языки с настоящим наследованием (Cue, Jsonnet, Dhall).

yaml
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.

# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports

# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
#   <<: *template    # ERROR in strict 1.2

# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
#   or a config language with proper inheritance
#   (e.g. Dhall, Cue, Jsonnet)

# Alternative without <<:
# just duplicate or use application-level templating
08

Теги типов

Встроенные теги

Встроенные теги используют префикс !! (сокращение для tag:yaml.org,2002:). Они принудительно задают тип независимо от вывода схемы. Частые теги: !!str, !!int, !!float, !!bool, !!null, !!binary, !!map, !!seq, !!omap, !!set, !!timestamp. Полезны, когда вывод угадал бы неверно.

yaml
# YAML tags use !! prefix for built-in types
# (the long form is tag:yaml.org,2002:)

# Common built-in tags
str: !!str hello
int: !!int 42
float: !!float 3.14
bool: !!bool true
null: !!null null
binary: !!binary "SGVsbG8="
map: !!map {a: 1}
seq: !!seq [1, 2]
omap: !!omap
  - a: 1
  - b: 2
set: !!set
  ? item1
  ? item2
timestamp: !!timestamp 2024-01-01T00:00:00Z
merge: !!merge "<<"   # the merge key tag

# Tags force a specific type regardless of inference
forced_str: !!str 42        # "42" string
forced_int: !!int "42"      # 42 integer
forced_bool: !!bool "yes"   # true

Принудительное задание типов

Теги принудительно задают тип, переопределяя вывод схемы. Чаще всего !!str используют, чтобы строки, похожие на числа, boolean или даты, не приводились. !!int и !!float могут разбирать числовые строки. Теги необходимы, когда приложению-хосту нужен конкретный тип.

yaml
# Without tags, type depends on schema inference
value: 42          # integer (Core schema)
value: "42"        # string (quoted)
value: !!str 42    # string (forced by tag)

# Common forcing scenarios
version: !!str 1.0       # "1.0" string, not float
phone: !!str 5551234     # string, not int
answer: !!str yes        # string, not bool (1.1)
region: !!str no         # string "no", not False (1.1)

# Force numeric parsing from strings
count: !!int "100"       # 100 integer
ratio: !!float "0.5"     # 0.5 float

# Force bool from strings
enabled: !!bool "yes"    # true
enabled: !!bool "off"    # false

# Force null
empty: !!null ""         # null
empty: !!null "~"        # null

Пользовательские теги

Пользовательские теги используют префикс ! и определяются приложением. Приложение-хост должно зарегистрировать конструктор для каждого тега. Безопасные загрузчики (рекомендуется) по умолчанию отвергают неизвестные теги — нужно явно разрешить. Теги конкретных библиотек (вроде python/object в PyYAML) могут быть опасны и отключены в безопасных загрузчиках.

yaml
# Application-specific tags use ! prefix
# The application's YAML loader must handle them

# Custom tag (application-defined)
person: !person
  name: Alice
  age: 30

# Tag with arguments
color: !color rgb(255, 0, 0)
point: !point [10, 20]

# Library-specific tags (PyYAML example)
# python/object/apply:module.func args
sorted_set: !!python/object/apply:sorted
  args:
    - [3, 1, 2]

# Ruby-specific (Psych)
# !ruby/object:ClassName

# Custom tags require custom constructors in code.
# Unknown tags usually cause errors in safe loaders.

Локальные и verbatim-теги

!prefix — для локальных тегов (определяемых приложением), !! — сокращение для глобальных тегов yaml.org, !<uri> — verbatim (без разрешения), а !prefix!short использует префиксы, объявленные через %TAG, для краткости. Локальные теги самые частые; verbatim важны для схем между инструментами.

yaml
# ! prefix — local tag (application-specific, no URI)
data: !myapp/data
  value: 42

# !! prefix — global built-in tag (resolved to yaml.org)
str: !!str hello

# !<full-uri> — verbatim tag (exact URI, no resolution)
binary: !<tag:example.com,2024:binary> "data"

# !tag!short — tag with prefix (resolved via %TAG directive)
%TAG !e! tag:example.com,2024:
data: !e!custom value
# resolves to tag:example.com,2024:custom

# %TAG directives declare prefixes
%TAG !yaml! tag:yaml.org,2002:
value: !yaml!str 42   # same as !!str

# Local tags are most common in app-specific YAML
# Verbatim tags are useful for cross-tool interoperability

Разрешение тегов

Разрешение тегов зависит от схемы. Failsafe (минимальная) трактует всё как строки, если не помечено тегом. Схема JSON добавляет int/float/bool/null. Схема Core (по умолчанию в YAML 1.2) расширяет JSON более мягким сопоставлением. Явные теги (!!) всегда переопределяют разрешение схемы.

yaml
# Tags are resolved by the schema (Core, JSON, Failsafe)
# Without explicit tags, the schema infers types

# Failsafe schema — only str, map, seq (no inference)
# Everything is a string unless tagged
failsafe_value: 42       # str "42"
failsafe_tagged: !!int 42  # int 42

# JSON schema — str, int, float, bool, null, map, seq
json_value: 42           # int
json_str: "42"           # str

# Core schema (default for YAML 1.2) — like JSON but
# with more lenient parsing (yes/no not bool, etc.)
core_value: 42           # int
core_bool: true          # bool
core_str: hello          # str

# Explicit tags override schema resolution
forced: !!str true       # str "true" (even in Core)

Теги, специфичные для приложения

Теги, специфичные для приложения, позволяют встраивать доменные объекты (Money, DateRange и т. д.) в YAML. Загрузчик должен зарегистрировать конструктор для каждого тега. Всегда используйте безопасные загрузчики, которые по умолчанию отвергают неизвестные теги, — никогда не позволяйте недоверенному YAML вызывать произвольные конструкторы (классическая уязвимость десериализации).

yaml
# Define your own tags for domain objects
# Example: a config loader for a custom app

# Tag a node as a "Money" object
price: !money "USD 19.99"

# Tag a node as a "DateRange"
range: !dateRange
  start: 2024-01-01
  end: 2024-12-31

# Tag nodes for custom parsing/validation
settings: !strict
  host: localhost
  port: 8080

# PyYAML example: register a constructor
# class MoneyLoader:
#     def __init__(self, value):
#         self.currency, self.amount = value.split()
#         self.amount = float(self.amount)
#
# yaml.add_constructor('!money', lambda l, n:
#     MoneyLoader(l.construct_scalar(n)))

# Safe loaders reject unknown tags — opt-in explicitly
# to avoid processing untrusted input with side effects.
09

Маркеры документов и директивы

Один документ

Один YAML-документ прекрасно работает без маркеров. Ведущий --- — соглашение, сигнализирующее «это YAML», и отграничение от простого текста. Маркер конца ... необязателен и редко используется в файлах с одним документом.

yaml
# A single YAML document needs no markers
key: value
list:
  - a
  - b

# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value

# The trailing ... (end marker) is optional
# for a single document
key: value
...

Несколько документов (поток)

YAML-поток — последовательность документов, разделённых ---. Каждый документ разбирается независимо. Потоки часты в Kubernetes (несколько объектов в одном файле), генераторах статических сайтов и логах. Используйте load_all() или эквивалент в вашем парсере для перебора документов.

yaml
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3

# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
#   for doc in yaml.safe_load_all(stream):
#       print(doc)

# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelines

Маркер конца документа (...)

Маркер ... явно завершает документ. Он необязателен в большинстве случаев, но полезен, когда контент может быть неоднозначным (например, литеральный блок, содержащий ---). Он также сигнализирует конец документа потоковым парсерам. Редок в рукописном YAML, но част в программном выводе.

yaml
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end

# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
  Some content
  ---
  that looks like a separator
...
---
next: document

# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)

# ... is also useful in programmatic output to flush

Директивы

Директивы идут перед контентом документа и настраивают парсер. %YAML задаёт версию; %TAG объявляет сокращения префиксов тегов. Директивы ограничены документом: они применяются только к следующему документу. Большинство конфигов опускает директивы и полагается на значения парсера по умолчанию (обычно 1.1 или двурежимный 1.2).

yaml
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value

# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value

# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello

# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.

Примеры потоков документов

Потоки документов широко используются. Kubernetes применяет их, чтобы упаковать несколько объектов (Namespace, Deployment, Service) в один файл. Шаблоны Helm, логи CI и генераторы статических сайтов (front matter и контент) тоже используют потоки. Каждый документ независим и может иметь свои директивы.

yaml
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: production
spec:
  ports:
    - port: 80

# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + body

Ловушки границ

Строка, начинающаяся с --- в колонке 0, всегда разделитель документов (вне блочных скаляров). Внутри блочных скаляров (|, >) --- это литеральный контент. Чтобы включить --- в колонке 0 в значение, сделайте отступ блока или сначала завершите документ через ... . --- с контентом в той же строке — маркер начала документа, а не разделитель.

yaml
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:

---
script: |
  echo hello
  ---  # this is INSIDE the block scalar — safe
next: value

# But this is NOT safe:
---
content: |
  line1
---
mistaken: this is a NEW document, not part of content!

# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.

# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.

# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value   # this is one document
10

Flow-стиль

Flow-последовательности

Flow-последовательности используют [ ] и ведут себя как массивы JSON. Пробелы и переводы строк внутри гибкие. В отличие от JSON, висячие запятые НЕ допускаются. Полезны для коротких плотных списков. Закавычивайте элементы, содержащие спецсимволы (запятые, скобки, двоеточия).

yaml
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Empty
empty: []

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Multi-line flow sequence (whitespace is flexible)
long: [
  alpha,
  beta,
  gamma
]

# Quoting inside flow
mixed: ["hello", 'world', 42, true]

# NO trailing comma
bad: [1, 2, 3,]   # parse error

Flow-отображения

Flow-отображения используют { } и ведут себя как объекты JSON. Ключи можно закавычивать, когда они содержат спецсимволы. Пробелы гибкие. Висячие запятые запрещены (в отличие от JSON). Используйте flow-отображения для коротких плотных данных; блочный стиль читаемее для крупных структур.

yaml
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Empty mapping
empty: {}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}

# Multi-line flow mapping
config: {
  host: localhost,
  port: 8080,
  debug: true
}

# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}

# NO trailing comma
bad: {a: 1, b: 2,}   # parse error

Смешение flow и block

Flow- и block-стили можно свободно смешивать в документе. Прагматичное правило: используйте block для структурных элементов (лучше читаемость с отступами) и flow для коротких inline-значений (списки скаляров, небольшие словари). Избегайте глубоко вложенного flow — он быстро становится нечитаемым.

yaml
# Mix flow and block styles freely
config:
  name: myapp
  ports: [80, 443]        # flow sequence in block mapping
  endpoints: {api: /v1, web: /}  # flow mapping in block

# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]

# Flow at top level
[top, level, flow]

# Block at top level
- block
- sequence

# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadable

Вложенный flow

Flow-стиль может вкладываться сколь угодно глубоко, но каждый уровень добавляет скобки, которые становятся нечитаемыми. После 1–2 уровней вложенности переходите на block ради читаемости. Блочный эквивалент глубоко вложенного flow почти всегда яснее для людей-сопровождающих.

yaml
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}

# Equivalent block:
# data:
#   users:
#     - name: Alice
#       tags:
#         - a
#         - b
#     - name: Bob

# Multi-line nested flow (rare but valid)
matrix: {
  rows: [
    [1, 2, 3],
    [4, 5, 6]
  ],
  cols: 3
}

# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".

Когда использовать flow

Используйте flow для коротких списков скаляров, небольших словарей поиска, однострочных записей и вывода, совместимого с JSON. Избегайте flow для длинных списков (трудно сканировать), глубоко вложенных структур (стена скобок) и всего, что требует inline-комментариев. Если сомневаетесь, предпочитайте block ради читаемости.

yaml
# Good uses of flow style:

# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]

# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}

# 3. Single-line records in a sequence
coordinates:
  - {x: 1, y: 2}
  - {x: 3, y: 4}
  - {x: 5, y: 6}

# 4. JSON-compatible output (flow is JSON-compatible)

# Bad uses of flow style:

# 1. Long lists (use block)
#   ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...]  # hard to read

# 2. Deeply nested (use block)
#   {a: {b: {c: {d: {e: value}}}}}  # unreadable

# 3. Anything with comments (flow doesn't allow inline comments well)

Оговорки flow-стиля

У flow-стиля есть оговорки: спецсимволы (запятые, двоеточия, скобки) нужно закавычивать; висячие запятые нельзя; комментарии неудобны; нет блочных скаляров | или > (используйте \n в двойных кавычках); однострочные изменения труднее диффать. Block дружелюбнее для конфигов под контролем версий.

yaml
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"]   # commas and colons need quoting
block:
  - a
  - b
  - c,d      # no quotes needed in block style
  - d:e      # no quotes needed in block style

# Caveat 2: no trailing commas
bad: [1, 2, 3,]   # error

# Caveat 3: comments are awkward in flow
config: {
  host: localhost,  # comment allowed but clunky
  port: 8080
}

# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"

# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)
11

Конвертация YAML и JSON

JSON — валидный YAML

YAML 1.2 спроектирован так, что JSON — строгое подмножество: любой JSON-документ является валидным YAML. Большинство YAML-парсеров спокойно читают JSON. Обратное неверно: такие возможности YAML, как комментарии, якоря, потоки документов и блочные скаляры, не являются валидным JSON.

yaml
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML

# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# So is this multi-line JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["a", "b"]
}

# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string)  # works
# JS:     YAML.load(json_string)       # works
# Go:     yaml.Unmarshal(json_bytes, &v)  # works (yaml.v3)

# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSON

Эквивалентные представления

JSON, блочный YAML и flow-YAML могут представлять одни и те же данные. JSON самый переносимый (в каждом языке есть JSON-парсер). Блочный YAML самый читаемый для людей. Flow-YAML — компактная золотая середина. Выбирайте по аудитории: инструменты (JSON) или люди (блочный YAML).

yaml
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# YAML block:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}

# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline data

Конвертация JSON в YAML

Конвертируйте JSON в YAML, разобрав JSON и выгрузив как YAML с default_flow_style=False (блочный стиль). Обязательные кавычки JSON отбрасываются там, где YAML их не требует. Следите за ключами, похожими на числа или boolean: в YAML их может понадобиться закавычить, чтобы сохранить строковый тип.

yaml
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)

# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}

# Output YAML:
# server:
#   host: localhost
#   port: 8080
# debug: true

# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preserved

Конвертация YAML в JSON

Конвертируйте YAML в JSON, разобрав, затем сериализовав в JSON. Оговорки: комментарии и теги теряются; якоря разворачиваются в обычные копии; потоки документов должны стать JSON-массивом; YAML-даты могут стать строками. Инструменты вроде yq упрощают это в командной строке.

yaml
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)

# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)

# Command-line tools:
# yq -o=json '.config' file.yaml        # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'

# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)

JSON-совместимое подмножество

JSON-совместимое подмножество YAML избегает комментариев, якорей, нескольких документов, тегов, блочных скаляров и простых строк, похожих на другие типы. Пребывание в этом подмножестве гарантирует чистые круговые преобразования в JSON. Полезно, когда одни и те же данные читают и YAML-, и JSON-потребители, или когда важно строгое сохранение типов.

yaml
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:

# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types

# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}

# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.

# Many YAML dumpers have a "json-compatible" mode.

Соображения кругового преобразования

Круговое преобразование YAML (разбор, затем выгрузка) часто теряет комментарии, имена якорей, порядок ключей, стиль кавычек и форматирование. ruamel.yaml (Python) имеет режим round-trip, сохраняющий комментарии и порядок. Для конфигов, редактируемых людьми, никогда не перезаписывайте слепо выводом дампера — сначала внимательно сравните diff.

yaml
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives

# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting

# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
#   without diffing carefully
12

Схемы YAML

Схема Failsafe

Схема Failsafe самая консервативная: она распознаёт только str, map и seq. Все скаляры — строки, если явно не помечены тегом. Полезна для недоверенного ввода (никаких сюрпризов неявного приведения) или как база для своих схем. Большинство продакшен-загрузчиков используют чуть более богатую схему.

yaml
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string

# Under Failsafe:
value: 42           # str "42" (NOT int)
flag: true          # str "true" (NOT bool)
empty: null         # str "null" (NOT null)
date: 2024-01-01    # str "2024-01-01" (NOT date)

# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null

# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas

# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.

Схема JSON

Схема JSON точно соответствует системе типов JSON: str, int, float, bool, null, map, seq. Она строже схемы Core: нет восьмеричных и двоичных литералов, нет разделителей-подчёркиваний, boolean только true/false, без вывода дат. Используйте для интеропа с JSON или строгого поведения типов.

yaml
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq

# Under JSON schema:
int: 42             # int
float: 3.14         # float
str: hello          # str
bool: true          # bool
null_val: null      # null
list: [1, 2, 3]     # seq
map: {a: 1}         # map

# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference

# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semantics

Схема Core

Схема Core — значение по умолчанию в YAML 1.2. Она расширяет JSON мягким разбором: hex (0x), octal (0o), binary (0b), подчёркивания в числах, float .inf/.nan. Boolean только true/false (не yes/no). Даты — строки (без вывода). Большинство современных парсеров по умолчанию использует Core или вариант, совместимый с 1.1.

yaml
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution

# Under Core schema:
int: 42             # int
neg: -17            # int
hex: 0xFF           # int (255)
oct: 0o17           # int (15)  [YAML 1.2 syntax]
bin: 0b1010         # int (10)
float: 3.14         # float
exp: 1.0e+3         # float
inf: .inf           # float
nan: .nan           # float
bool: true          # bool (only true/false, not yes/no)
null: null          # null (also ~, empty)
str: hello          # str
date: 2024-01-01    # str (Core does NOT infer dates)

# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)

# Most modern parsers default to Core or close to it.

YAML 1.1 против 1.2

YAML 1.1 (по умолчанию в PyYAML) трактует yes/no/on/off как boolean, а числа с ведущим 0 — как восьмеричные: знаменитые источники багов (норвежское 'no' превращается в false). YAML 1.2 (текущая спецификация) ограничивает boolean true/false и использует 0o для восьмеричных. Всегда проверяйте значение парсера по умолчанию и закавычивайте неоднозначные строки.

yaml
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes       # true (yes/no/on/off are booleans)
octal_1_1: 017      # 15 (leading 0 = octal)
sexagesimal: 1:30   # 90 (base-60!) - obscure feature

# YAML 1.2 (current spec)
bool_1_2: yes       # str "yes" (only true/false are bool)
octal_1_2: 0o17     # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"

# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2

# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish

# Always check your parser's default schema!

Различия разрешения типов

Разрешение типов различается между парсерами YAML 1.1 и 1.2: yes/no/on/off, числа с ведущим нулём и шестидесятеричные литералы разбираются по-разному. Смягчайте закавычиванием неоднозначных строк, фиксацией версии через %YAML, явными тегами и тестированием на всех целевых парсерах.

yaml
# Same YAML, different parsers, different types:
value: yes

# PyYAML (1.1):        True (bool)
# js-yaml (1.1):       true (bool)
# ruamel (1.2):        "yes" (str)
# Go yaml.v3 (1.2):    "yes" (str)
# Strict 1.2:          "yes" (str)

value: 010

# PyYAML (1.1):        8 (int, octal)
# ruamel (1.2):        "010" (str)
# Go yaml.v3 (1.2):    "010" (str)

value: 1.0

# All:                 1.0 (float) - consistent

value: true

# All:                 true (bool) - consistent

# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsers

Выбор схемы

Выбирайте схему по сценарию: 1.2 Core для новых проектов (предсказуемо), 1.1 для интеропа с PyYAML (или закавычивайте неоднозначные строки), Failsafe или JSON для недоверенного ввода, JSON-схему для интеропа с JSON. Для конфигов 1.2 Core плюс закавычивание неоднозначных строк («no», «010» и т. п.) — самая безопасная комбинация.

yaml
# Recommendations for choosing a schema:

# 1. For NEW projects: use YAML 1.2 Core schema
#    - More predictable (no yes/no surprises)
#    - Modern parsers support it
#    - ruamel.yaml, Go yaml.v3 default to it

# 2. For INTEROP with existing PyYAML code:
#    - Either accept 1.1 semantics
#    - Or use ruamel.yaml with 1.2 + preserve 1.1 features
#    - Quote all ambiguous strings explicitly

# 3. For UNTRUSTED input: use Failsafe or JSON schema
#    - No implicit type coercion
#    - Smaller attack surface
#    - Predictable behavior

# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
#    - "no", "yes", "on", "off", "010", "1.0" should be quoted
#    - Document your schema choice
#    - Lint with yamllint

# 5. For JSON INTEROP: use JSON schema
#    - Same types as JSON
#    - Round-trips cleanly
13

Линт и валидация YAML

yamllint

yamllint — стандартный линтер YAML (Python). Он ловит синтаксические ошибки, проблемы отступов, хвостовые пробелы, отсутствующие маркеры документов и другое. Используйте его в CI и pre-commit хуках, чтобы ловить проблемы YAML рано. Строгий режим (-s) трактует предупреждения как ошибки.

yaml
# yamllint is the standard YAML linter
# Install: pip install yamllint

# Lint a file
# yamllint config.yaml

# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml

# Output example:
# config.yaml
#   3:4       error    mapping values are not allowed here
#   5:1       error    syntax error: found character '	' that cannot start any token
#   8:3       warning  missing document start "---"
#   12:5      warning  comment is not indented like content

# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml

# Lint a directory (recursive)
# yamllint -d path/to/dir

# Read from stdin
# cat config.yaml | yamllint -

Конфигурация линта

Настраивайте yamllint через .yamllint.yml. Расширьте профиль (default или strict), затем переопределите отдельные правила: отступы, длину строки, стиль кавычек, комментарии, хвостовые пробелы, маркеры документов. Подстройте под стиль команды. Запускайте в CI для единообразия.

yaml
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config

# Use a built-in profile
extends: default

# Or use a stricter profile
# extends: strict

# Override specific rules
rules:
  # Require document start marker
  document-start: disable
  # Enforce 2-space indentation
  indentation:
    spaces: 2
    indent-sequences: true
  # Max line length
  line-length:
    max: 120
    allow-non-breakable-words: true
  # Disallow trailing spaces
  trailing-spaces: enable
  # Require consistent quoting
  quoted-strings:
    quote-type: double
    required: only-when-needed
  # Disallow comments without space before #
  comments:
    require-starting-space: true
    min-spaces-from-content: 1

Частые синтаксические ошибки

Частые ошибки YAML: табы для отступов (допустимы только пробелы), двоеточие без следующего пробела, незакавыченные строки с двоеточиями (разбираются как отображения), висячие запятые в flow-стиле, несогласованные отступы и дубликаты ключей. Линтер ловит всё это автоматически.

yaml
# Error: tab characters for indentation
# bad:
# 	key: value   <- tab not allowed
# Fix: use spaces only

# Error: colon without space
# bad:  key:value
# good: key: value

# Error: unquoted special characters
# bad:  url: http://example.com:8080   <- parsed as mapping
# good: url: "http://example.com:8080"

# Error: trailing comma in flow
# bad:  list: [1, 2, 3,]
# good: list: [1, 2, 3]

# Error: inconsistent indentation
# bad:
#   key1: value
#    key2: value   <- one extra space
# good:
#   key1: value
#   key2: value

# Error: duplicate keys (some parsers warn)
# bad:
#   key: first
#   key: second
# good: rename one

Ошибки табов и пробелов

Табы строго запрещены для структурных отступов YAML — причина ошибок разбора номер один. Табы внутри строковых значений (блочные скаляры, строки в кавычках) допустимы. Настройте редактор на пробелы (expandtab) для YAML-файлов. Находите проблемные строки через grep -P '\t'.

yaml
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.

# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"

# Tabs are allowed INSIDE string values:
script: |
  #!/bin/bash
  if [ -f file ]; then   # this is fine (literal content)
  \techo found           # \t inside block scalar is OK

# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx

# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2

# Detect tabs:
# grep -P '\t' file.yaml   (finds offending lines)

Поиск дубликатов ключей

Дубликаты ключей в отображении не рекомендуются и являются частым источником багов (тихое переопределение, где побеждает последний). yamllint находит их правилом key-duplicates (включено по умолчанию). Частые причины: ошибки копирования и плохое разрешение merge-конфликтов. Всегда линтуйте в CI, чтобы ловить их рано.

yaml
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).

config:
  host: localhost
  port: 8080
  host: prod.example.com   # silent override!

# yamllint catches these:
#   4:3  error  duplication of key "host" in mapping

# Enable in .yamllint.yml:
# rules:
#   key-duplicates: enable

# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)

# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.

Валидация схемы

Валидируйте структуру YAML через JSON Schema (работает, потому что YAML — надмножество JSON). Для Kubernetes используйте kubeval или kubectl --dry-run. Для общего конфига используйте yamllint (синтаксис и стиль) плюс jsonschema (структура) или Cue (язык схем). Встройте валидацию в pre-commit хуки и CI.

yaml
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)

# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)

# Tools for Kubernetes YAML:
# kubeval            - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest           - policy-based validation (OPA)

# Tools for general YAML:
# yamllint           - syntax + style
# jsonschema-cli     - JSON Schema validation
# cue                - schema + validation language
# dataladen          - config validation

# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.32.0
#     hooks:
#       - id: yamllint
#         args: [-s]
14

YAML Docker Compose

Определение сервиса

Файлы Docker Compose определяют многоконтейнерные приложения. Ключи верхнего уровня: version, services, volumes, networks, configs, secrets. Каждый сервис задаёт image/build, ports, volumes, environment, depends_on, политику restart. Тома, объявленные на верхнем уровне, именованные и персистентные.

yaml
# docker-compose.yml — multi-container apps
version: "3.9"   # compose file format version

services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped
    depends_on:
      - api

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - DB_URL=postgres://db:5432/app
    ports:
      - "8080:8080"
    restart: always

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always

volumes:
  db_data:

Тома и сети

Тома Compose бывают bind mount (host:container), именованные (объявлены в верхнеуровневых volumes) или анонимные. Суффикс :ro делает монтирование read-only. Сети изолируют сервисы; internal: true блокирует внешний доступ. Именованные тома сохраняют данные между пересозданиями контейнеров.

yaml
services:
  web:
    image: nginx
    volumes:
      # Bind mount: host:container
      - ./html:/usr/share/nginx/html:ro
      # Named volume: name:container
      - shared_data:/data
      # Anonymous volume
      - /tmp/cache
    networks:
      - frontend
      - backend

  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db_data:
    driver: local
  shared_data:
    driver: nfs
    driver_opts:
      type: nfs
      device: ":/path/to/share"

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

Переменные окружения

Compose поддерживает три стиля env-переменных: список (KEY=value), словарь (KEY: value) и env_file. ${VAR} интерполируется из shell хоста или файла .env при разборе; ${VAR:-default} даёт значение по умолчанию. Используйте $$, чтобы экранировать литеральный $. Файл .env в корне проекта загружается автоматически.

yaml
services:
  api:
    image: myapi
    # Method 1: list of KEY=value
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    # Method 2: map (cleaner)
    environment:
      NODE_ENV: production
      LOG_LEVEL: info
    # Method 3: file
    env_file:
      - .env
      - .env.production
    # Interpolation from host environment
    environment:
      - API_KEY=${API_KEY}     # from shell
      - PORT=${PORT:-8080}      # default 8080

# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...

# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5   # produces price_$5

Depends, healthchecks и restart

depends_on с condition: service_healthy ждёт прохождения healthcheck зависимости перед запуском. Healthchecks используют test (CMD или CMD-SHELL), interval, timeout, retries, start_period. Политики restart: no, always, unless-stopped (переживает перезагрузки, но уважает ручную остановку), on-failure.

yaml
services:
  api:
    image: myapi
    depends_on:
      db:
        condition: service_healthy   # wait for db healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

# restart policies:
# no              - never restart (default)
# always          - always restart on stop
# unless-stopped  - restart unless manually stopped
# on-failure      - restart only on non-zero exit

Override-файлы

Compose сливает override-файлы поверх базового. docker-compose.override.yml применяется автоматически. Отображения сливаются глубоко (переопределения побеждают); последовательности обычно заменяются (не дописываются) — следите за ports и volumes. Используйте флаги -f, чтобы задать явный порядок файлов для конфигов конкретных окружений.

yaml
# docker-compose.yml — base
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - ENV=base

# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
  web:
    ports:
      - "8080:80"      # overrides "80:80"
    environment:
      - DEBUG=true     # added
      - ENV=override   # overrides ENV=base
    volumes:
      - ./dev.conf:/etc/nginx/conf.d/default.conf

# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up

# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
#   ports/depends_on/volumes are exceptions in some versions

# Use -f to specify explicit file order

Профили и возможности Compose

Профили позволяют включать сервисы по выбору (например, debug, test, ci) флагом --profile. Другие возможности v3: init (корректная обработка сигналов как PID 1), extends (наследование от другого сервиса), configs и secrets (монтируются как файлы), deploy (размещение, реплики и ресурсы Swarm). Профили хороши, чтобы держать один compose-файл для нескольких окружений.

yaml
# Profiles — opt-in services
services:
  web:
    image: nginx
    # no profile: always started

  debug:
    image: busybox
    profiles: ["debug"]   # only with --profile debug

  loadtest:
    image: locust
    profiles: ["test", "ci"]

# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up

# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1

services:
  worker:
    image: worker
    init: true   # proper signal handling
    extends:
      service: base   # inherit fields
    configs:
      - config1
    secrets:
      - api_key

configs:
  config1:
    file: ./config.toml
secrets:
  api_key:
    file: ./api_key.txt
15

YAML Kubernetes

Структура объекта

У каждого объекта Kubernetes есть apiVersion, kind, metadata и spec. apiVersion — группа и версия (например, apps/v1, v1 для core). metadata включает name, namespace, labels, annotations. spec — желаемое состояние: Kubernetes стремится привести реальность к spec. status задаёт система.

yaml
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1        # API group + version
kind: Deployment           # object type
metadata:                  # identity
  name: my-app
  namespace: production
  labels:
    app: my-app
    tier: backend
  annotations:
    deployment.kubernetes.io/revision: "1"
spec:                      # desired state
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080

# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)

Labels и селекторы

Labels идентифицируют и группируют объекты; селекторы запрашивают по labels. Поддерживаются селекторы на равенстве (key=value) и на множествах (In, NotIn, Exists, DoesNotExist). Annotations хранят неидентифицирующие метаданные (описания, контакты, конфигурацию инструментов). Labels — для выбора; annotations — для дополнительной информации.

yaml
# Labels — identify and group objects
metadata:
  labels:
    app: my-app
    tier: backend
    env: production
    version: "1.0"

# Selectors — query objects by labels
# Equality-based
selector:
  matchLabels:
    app: my-app
    env: production

# Set-based
selector:
  matchExpressions:
    - {key: tier, operator: In, values: [backend, api]}
    - {key: env, operator: NotIn, values: [dev]}
    - {key: version, operator: Exists}

# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production

# Annotations — non-identifying metadata
metadata:
  annotations:
    description: "My app deployment"
    contact: "[email protected]"

Pod spec

Spec Pod определяет контейнеры, их образы, порты, env-переменные (литеральные или из secrets и configmaps), ресурсы (requests/limits), пробы (readiness/liveness), тома и volumeMounts. Pods — минимальная развёртываемая единица, но обычно их создают через Deployments, а не напрямую.

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: app
      image: my-app:1.0
      ports:
        - containerPort: 8080
          name: http
      env:
        - name: LOG_LEVEL
          value: info
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: secret-key
      resources:
        requests: {cpu: 100m, memory: 128Mi}
        limits: {cpu: 500m, memory: 512Mi}
      readinessProbe:
        httpGet: {path: /health, port: 8080}
        initialDelaySeconds: 5
        periodSeconds: 10
      volumeMounts:
        - name: config
          mountPath: /etc/config
  volumes:
    - name: config
      configMap:
        name: app-config
  restartPolicy: Always

Deployment

Deployment управляет ReplicaSets и Pods. spec.replicas задаёт желаемое количество. strategy.type может быть RollingUpdate (по умолчанию, управляется maxSurge/maxUnavailable) или Recreate. Шаблон pod (spec.template) определяет, как создаются pod'ы. Управляйте rollout'ами через kubectl rollout status/undo/history.

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          resources:
            requests: {cpu: 100m, memory: 128Mi}
            limits: {cpu: 500m, memory: 512Mi}
          readinessProbe:
            httpGet: {path: /ready, port: 8080}
  # Rollback / history
  # kubectl rollout status deployment/my-app
  # kubectl rollout undo deployment/my-app
  # kubectl rollout history deployment/my-app

Service

Service открывает Pods как сетевой сервис. type ClusterIP (по умолчанию) только внутренний; NodePort открывает на каждом узле; LoadBalancer создаёт облачный LB; ExternalName — DNS CNAME. selector направляет трафик к подходящим pod'ам. ports сопоставляют порт сервиса с targetPort контейнера (число или имя).

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: ClusterIP      # ClusterIP (default), NodePort, LoadBalancer, ExternalName
  selector:
    app: my-app        # routes to pods with these labels
  ports:
    - name: http
      port: 80         # service port
      targetPort: 8080 # container port (or named port)
      protocol: TCP
    - name: https
      port: 443
      targetPort: 8443

# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service

# Service types:
# ClusterIP    - internal cluster IP (default)
# NodePort     - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)

ConfigMap и Secret

ConfigMaps хранят нечувствительную конфигурацию (строки или файлы); Secrets — чувствительные данные (base64 в data или открытый текст в stringData). Оба потребляются через env-переменные (valueFrom) или монтируются как тома. Secrets по умолчанию НЕ шифруются — включите шифрование в покое и ограничьте доступ через RBAC.

yaml
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  log_level: info
  max_connections: "100"
  config.yaml: |
    server:
      host: 0.0.0.0
      port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  # base64-encoded values
  api_key: c2VjcmV0LWtleS0xMjM=   # echo -n 'secret-key-123' | base64
  db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
#   api_key: secret-key-123

# Consumed by pods:
# env:
#   - name: API_KEY
#     valueFrom:
#       secretKeyRef:
#         name: app-secrets
#         key: api_key
# volumes:
#   - name: config
#     configMap:
#       name: app-config
16

Конфигурация CI/CD (GitHub Actions и GitLab CI)

Workflow GitHub Actions

Workflow GitHub Actions живут в .github/workflows/. on: триггеры (push, PR, schedule, workflow_dispatch). jobs содержат runs-on и steps. uses: ссылается на actions, run: выполняет shell. Выражения используют синтаксис ${{ }} — внутри YAML-шаблонных литералов их нужно экранировать как \${{ }}.

yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: npm run build
        env:
          NODE_ENV: production

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint

# ${{ }} is GitHub Actions expression syntax
# MUST be escaped as ${{ }} in YAML template literals
# (here we use literal text, no escaping needed)

Пайплайн GitLab CI

GitLab CI живёт в .gitlab-ci.yml. stages задают порядок пайплайна. У jobs есть stage, image, script и множество опций (only/except, rules, when, artifacts, environment). Переменные используют синтаксис $VAR (экранирование в блочных скалярах YAML не нужно). when: manual требует клика для деплоя.

yaml
# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  NODE_ENV: production
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test
  artifacts:
    reports:
      junit: test-results.xml
  coverage: '/Lines.*:\s(\d+\.\d+)\%/'

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t myapp:$IMAGE_TAG .
    - docker push myapp:$IMAGE_TAG
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
  only:
    - main
  when: manual   # require manual trigger

Matrix-сборки

Matrix-сборки запускают job несколько раз с разными переменными. GitHub Actions использует strategy.matrix с include/exclude. GitLab использует parallel.matrix. fail-fast: false не даёт одному сбою отменить соседние. Полезно для кросс-платформенного тестирования нескольких версий. Синтаксис ${{ }} нужно экранировать в литералах YAML.

yaml
# GitHub Actions matrix
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          - os: windows-latest
            node: 18
        include:
          - os: ubuntu-latest
            node: 20
            experimental: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

# GitLab CI matrix (parallel matrix):
# test:
#   image: node:${NODE_VERSION}
#   parallel:
#     matrix:
#       - NODE_VERSION: [18, 20, 22]
#         OS: [linux, macos]

Переиспользуемые workflow и include

Обе системы поддерживают переиспользование. GitHub Actions использует reusable workflows (триггер workflow_call), вызываемые через uses:. GitLab использует include (project, local, template, remote). Переиспользование снижает дублирование общей CI-логики. Передавайте inputs и secrets явно, чтобы workflow оставались компонуемыми и аудируемыми.

yaml
# GitHub Actions: reusable workflow
# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          TOKEN: ${{ secrets.token }}

# Caller:
# jobs:
#   build:
#     uses: ./.github/workflows/reusable.yml
#     with:
#       node-version: '20'
#     secrets:
#       token: ${{ secrets.MY_TOKEN }}

# GitLab CI: include
# include:
#   - project: 'ci/templates'
#     file: '/node.yml'
#   - local: '/.gitlab/extra.yml'
#   - template: Jobs/SAST.gitlab-ci.yml

Якоря в CI-конфигах

Якоря YAML сокращают дублирование в CI-конфигах. GitLab CI активно их использует: определите скрытый job (.template) с &anchor, затем <<: *anchor для слияния. GitHub Actions поддерживает якоря, но не поощряет их между job'ами (предпочитайте reusable workflows). Якоря делают конфиги DRY, но усложняют трассировку — используйте умеренно.

yaml
# YAML anchors reduce duplication in CI configs
# GitLab CI commonly uses anchors

.default_template: &default_template
  image: node:20
  before_script:
    - npm ci
  cache:
    paths:
      - node_modules/

test:
  <<: *default_template
  script:
    - npm test

lint:
  <<: *default_template
  script:
    - npm run lint

build:
  <<: *default_template
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

# GitHub Actions supports anchors too (since 2022):
# jobs:
#   base: &base
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#   test:
#     uses: ./.github/workflows/reusable.yml
#   # Anchors across jobs are limited — prefer reusable workflows

Окружения и секреты

Окружения GitHub Actions ограничивают деплой (требуют одобрения, ограничивают ветки) и хранят секреты уровня окружения. Секреты упоминаются через ${{ secrets.NAME }}. GitLab использует protected (ограниченные веткой) и masked (скрытые в логах) переменные, задаваемые в UI. Никогда не логируйте секреты — они могут утечь в вывод ошибок.

yaml
# GitHub Actions: environments & secrets
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production        # requires approval if configured
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
          ENV: production

# Secret scopes:
# - Repository secrets: available to all workflows
# - Environment secrets: only when job uses that environment
# - Organization secrets: shared across repos

# GitLab CI: protected/masked variables
# variables:
#   # defined in UI: Settings > CI/CD > Variables
#   # - Protected: only on protected branches/tags
#   # - Masked: hidden in job logs
# deploy:
#   script:
#     - ./deploy.sh
#   environment:
#     name: production
#   only:
#     - main
17

Вопросы безопасности

Риски десериализации

Десериализация YAML опасна, потому что теги вроде !!python/object/apply могут вызывать произвольные функции. yaml.load() в PyYAML был небезопасен по умолчанию до 5.1 (выполнение кода из недоверенного ввода). Всегда используйте yaml.safe_load() для недоверенного ввода: он отвергает теги инстанцирования объектов. В других языках похожие опасности (SnakeYAML, Psych).

yaml
# YAML deserialization can be DANGEROUS.
# Some loaders let YAML instantiate arbitrary objects.

# DANGEROUS (PyYAML < 5.1, default was unsafe):
# data = yaml.load(untrusted_input)
# An attacker can craft YAML that runs arbitrary code:
# !!python/object/apply:os.system ["rm -rf /"]

# Other dangerous tags:
# !!python/object/apply:...     # call any Python function
# !!python/object/new:...       # instantiate any class
# !ruby/object:...               # Ruby object instantiation
# !java/object:...               # Java (SnakeYAML)

# Safe loaders reject these tags by default.
# Modern PyYAML (>= 5.1): yaml.load() requires a SafeLoader
# yaml.safe_load() is ALWAYS safe.

# Rule of thumb:
# - NEVER use yaml.load() on untrusted input
# - ALWAYS use yaml.safe_load() (or full_load on trusted files)
# - Or use a schema-validated loader

safe_load против load

Всегда используйте safe_load (Python), safe_load (Ruby Psych) или безопасные схемы по умолчанию (js-yaml, Go yaml.v3). PyYAML 5.1+ требует явный Loader для yaml.load(). full_load допускает стандартные теги, но не произвольные объекты — используйте только для доверенных файлов. Безопасные загрузчики отвергают все теги инстанцирования объектов.

yaml
# Python (PyYAML) — the classic safe/unsafe distinction

# SAFE: safe_load rejects all custom tags
import yaml
data = yaml.safe_load(untrusted_yaml)   # ALWAYS use this

# SAFE: load with SafeLoader (explicit)
data = yaml.load(untrusted_yaml, Loader=yaml.SafeLoader)

# FULL (trusted files only): full_load allows standard tags
# but not arbitrary python objects
data = yaml.full_load(trusted_yaml)

# UNSAFE: UnsafeLoader allows !!python/object — DANGEROUS
data = yaml.load(untrusted_yaml, Loader=yaml.UnsafeLoader)  # NEVER on untrusted

# PyYAML 5.1+ requires Loader argument for yaml.load()
# (raises error without it) — safety improvement.

# Other languages:
# JS (js-yaml): yaml.load(str) uses DEFAULT_SAFE_SCHEMA
# Go (yaml.v3): no object instantiation (safe by design)
# Ruby (Psych): Psych.safe_load is the safe variant
# Java (SnakeYAML): SafeConstructor for safe loading

Эксплуатация локальных тегов

Пользовательские теги (!include, !env, !file, !exec, !template) можно эксплуатировать даже без !!python/object. !include, читающий файлы, можно обмануть, чтобы прочитать /etc/passwd или .ssh/id_rsa через path traversal. Аудируйте каждый свой конструктор: валидируйте пути по белым спискам, отклоняйте абсолютные пути и ../, ограничивайте загрузчик песочницей.

yaml
# Even non-builtin tags can be exploited if your loader
# registers constructors that have side effects.

# Example: a "harmless" custom tag
# yaml.add_constructor('!include', include_file)
#
# If !include reads files from disk, an attacker can
# craft YAML to read sensitive files:
# config: !include /etc/passwd
# or:
# config: !include /etc/shadow
# or:
# config: !include ../../../.ssh/id_rsa

# Mitigation:
# 1. Validate the included path against an allowlist
# 2. Restrict !include to a specific directory
# 3. Refuse absolute paths and ../ traversal
# 4. Run the loader in a sandbox

# Other "innocent" tags that can be exploited:
# !env VAR_NAME        -> leaks env vars
# !exec "command"      -> arbitrary command execution
# !file /path          -> file disclosure
# !template <% ... %>  -> code injection

# Audit every custom constructor for side effects.

Billion Laughs и DoS

Атака Billion Laughs использует вложенные алиасы, раздувая крошечный документ до гигабайт памяти (10 алиасов на уровень, 5 уровней = 10^9 ссылок). Смягчайте лимитами глубины алиасов, лимитами общего размера, потоковыми парсерами и отклонением чрезмерной вложенности. Следите также за глубокой вложенностью (переполнение стека) и огромными плоскими коллекциями.

yaml
# "Billion Laughs" attack — exponential expansion via aliases
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol","lol"]
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a,*a]
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b,*b]
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c,*c]
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d,*d]

# This 5-line document expands to ~10^9 string references
# consuming gigabytes of memory on parse.

# Mitigations:
# 1. Limit alias depth (some parsers do this)
# 2. Limit total parsed size / memory
# 3. Use a streaming parser for untrusted input
# 4. PyYAML has a limit but not all parsers do
# 5. Reject documents with excessive alias nesting

# Other DoS vectors:
# - Very deep nesting (parser stack overflow)
# - Huge flat sequences/mappings (memory)
# - Pathological number formats (regex backtracking)
# - Quadratic blowup via duplicate keys

# For untrusted input: set hard size + depth limits.

Валидация ввода

Слоистая валидация: (1) лимит размера, (2) safe_load для отклонения опасных тегов, (3) проверка типа (ожидаем dict, а не list), (4) валидация схемы (JSON Schema, Pydantic, Cue), (5) доменная валидация (бизнес-правила вроде диапазона портов). Каждый слой ловит разные атаки. Никогда не доверяйте структуре — всегда валидируйте перед использованием.

yaml
# Layered defense for untrusted YAML input:

# 1. Size limit (reject oversized input)
MAX_SIZE = 1024 * 1024  # 1 MB
if len(input_text) > MAX_SIZE:
    raise ValueError("input too large")

# 2. Safe parser (rejects dangerous tags)
import yaml
try:
    data = yaml.safe_load(input_text)
except yaml.YAMLError as e:
    raise ValueError(f"invalid YAML: {e}")

# 3. Type check (expect a mapping, not a list)
if not isinstance(data, dict):
    raise ValueError("expected a mapping at top level")

# 4. Schema validation (JSON Schema, Pydantic, etc.)
from pydantic import BaseModel, ValidationError
class Config(BaseModel):
    host: str
    port: int = 8080
try:
    config = Config(**data)
except ValidationError as e:
    raise ValueError(f"schema validation failed: {e}")

# 5. Domain validation (business rules)
if config.port < 1 or config.port > 65535:
    raise ValueError("port out of range")

Рекомендации библиотек

Выбирайте библиотеки, безопасные по умолчанию: PyYAML (safe_load), ruamel.yaml, js-yaml (безопасный по умолчанию), Go yaml.v3, Psych.safe_load, SnakeYAML с SafeConstructor, serde_yaml. Избегайте yaml.load без явного безопасного загрузчика. Фиксируйте свежие версии ради патчей безопасности. Аудируйте свои конструкторы. Читайте документацию библиотеки по безопасности.

yaml
# Safe-by-default YAML libraries by language:

# Python:
#   - PyYAML >= 5.1 (yaml.safe_load)
#   - ruamel.yaml (safe by default, round-trip mode)
#   AVOID: yaml.load without explicit SafeLoader

# JavaScript/TypeScript:
#   - js-yaml (yaml.load uses DEFAULT_SAFE_SCHEMA)
#   AVOID: yaml.load with DEFAULT_FULL_SCHEMA on untrusted

# Go:
#   - gopkg.in/yaml.v3 (no object instantiation, safe)
#   AVOID: yaml.v2 has subtle differences, prefer v3

# Ruby:
#   - Psych (Psych.safe_load)
#   AVOID: YAML.load (uses unsafe loader in old Ruby)

# Java:
#   - SnakeYAML with SafeConstructor
#   AVOID: new Yaml() without SafeConstructor on untrusted
#   (SnakeYAML had CVEs from unsafe loading)

# Rust:
#   - serde_yaml (safe by design, no arbitrary types)

# General rule:
# - Read the library's security docs
# - Pin to a recent version (security patches)
# - Use safe_load / SafeConstructor / safe schema
# - Audit custom constructors for side effects
18

Лучшие практики

Согласованные отступы

Используйте 2 пробела последовательно (де-факто стандарт), никогда табы. Настройте редактор на вставку пробелов для YAML. Используйте форматтеры (prettier, yamlfixer) и линтеры (yamllint) для единообразия. Несогласованные отступы — самая частая ошибка YAML, ломающая разбор.

yaml
# Use 2 spaces for indentation (most common)
# NEVER use tabs (YAML forbids them)

# GOOD
server:
  host: localhost
  port: 8080
  routes:
    - path: /api
      handler: apiHandler
    - path: /web
      handler: webHandler

# BAD (inconsistent)
# server:
#    host: localhost
#   port: 8080      # wrong indent

# Configure your editor:
# VS Code: "[yaml]": {"editor.insertSpaces": true, "editor.tabSize": 2}
# Vim:     autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab
# Emacs:   (add-hook 'yaml-mode-hook
#           (lambda () (setq yaml-indent-offset 2)))

# Use a formatter:
# prettier (with yaml plugin) normalizes indentation
# yamllint checks it
# yamlfixer auto-fixes issues

Стратегия кавычек

Закавычивайте строки, похожие на числа, boolean, null или даты; содержащие двоеточия, запятые и спецсимволы; или начинающиеся с индикаторов (- ? : * & ! | > ' " % @). В остальном предпочитайте простые (без кавычек) ради читаемости. Двойные кавычки — для escape-последовательностей (\n, \t), одинарные — для литеральных строк с апострофами.

yaml
# Quote strings when:
# 1. They look like another type (number, bool, null, date)
version: "1.0"        # string, not float
answer: "yes"         # string, not bool (1.1)
region: "no"          # string "no", not False (1.1)
date: "2024-01-01"    # string, not date
phone: "555-1234"     # string, not number

# 2. They contain special characters
url: "https://example.com:8080"   # colon
list: "a, b, c"                    # comma
expr: "value:with:colons"          # colons

# 3. They start with special indicators (-, ?, :, *, &, !, |, >, ', ", %, @, `)
flag: "-not-a-list"
key: "?not-a-complex-key"

# Don't quote otherwise — plain is more readable
name: Alice            # no quotes needed
path: /usr/local/bin   # no quotes needed

# Prefer double quotes for escapes (\n, \t)
# Prefer single quotes for literal strings with apostrophes
greeting: "Hello\nWorld"
possessive: 'Alice''s car'

Избегайте табов и других ловушек

Избегайте частых ловушек: табы (запрещены — используйте пробелы), незакавыченные yes/no/on/off (неоднозначность 1.1 и 1.2), незакавыченные строки с двоеточиями, хвостовые пробелы, окончания строк CRLF (используйте LF), BOM (сохраняйте UTF-8 без BOM) и очень длинные строки (переносите блочными скалярами). Линтер ловит большинство из них.

yaml
# Pitfall 1: tabs for indentation (FORBIDDEN)
# Configure editor to use spaces

# Pitfall 2: yes/no/on/off as strings (1.1 vs 1.2)
# Always quote: "yes", "no", "on", "off"

# Pitfall 3: unquoted strings with colons
# bad:  url: http://x:8080
# good: url: "http://x:8080"

# Pitfall 4: trailing whitespace
# Some parsers are strict; linters always flag it
key: value   # <- no trailing spaces

# Pitfall 5: Windows line endings (CRLF)
# Use LF (\n) only — CRLF can cause subtle issues
# .gitattributes: *.yaml text eol=lf

# Pitfall 6: BOM at start of file
# Save as UTF-8 without BOM

# Pitfall 7: very long lines
# Wrap with block scalars or flow style
description: >
  This is a long description that wraps
  across multiple lines for readability.

# Pitfall 8: inconsistent key ordering
# Group related keys, be consistent

Фиксация версии и документирование схемы

Фиксируйте версию YAML через %YAML 1.2, если различия 1.1 и 1.2 важны. Документируйте схему: обязательные и необязательные поля, типы, значения по умолчанию, диапазоны — в комментариях, файле JSON Schema или README. Фиксируйте версии схемы в коде, чтобы валидация конфига была воспроизводимой. Это снижает трение онбординга и ошибки конфигурации.

yaml
# Pin the YAML version if it matters
%YAML 1.2
---
key: value

# Document your schema expectations in comments:
# Required fields:
#   - host: string (hostname or IP)
#   - port: integer (1-65535)
# Optional fields:
#   - tls: boolean (default: false)
#   - cert: string (path, required if tls: true)

config:
  host: example.com
  port: 443
  tls: true
  cert: /etc/ssl/cert.pem

# Or use a JSON Schema file (config.schema.json)
# and reference it from your docs / CI:
# "Validated against schema v1.2; see config.schema.json"

# For libraries, document the schema in the README:
# ## Configuration
# The config.yaml file must contain:
# - host (str, required)
# - port (int, required, 1-65535)
# - tls (bool, optional, default: false)

# Pin schema versions in code:
# CONFIG_SCHEMA_VERSION = "1.2"
# validate(data, schema_v1_2)

Линт в CI

Встройте линт YAML в CI (GitHub Actions, GitLab CI) и pre-commit хуки. Используйте yamllint для синтаксиса и стиля и prettier для форматирования. Интеграция с редактором (расширение YAML для VS Code, yaml-language-server) даёт inline-линтинг и валидацию схемы. Ловить ошибки YAML в CI намного дешевле, чем в продакшене.

yaml
# .github/workflows/lint.yml
name: Lint YAML
on: [push, pull_request]
jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint
        run: yamllint -s .

# GitLab CI:
# yamllint:
#   image: python:3.12
#   script:
#     - pip install yamllint
#     - yamllint -s .

# Pre-commit hook (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.35.1
#     hooks:
#       - id: yamllint
#         args: [-s, --config-file, .yamllint.yml]
#   - repo: https://github.com/pre-commit/mirrors-prettier
#     rev: v3.1.0
#     hooks:
#       - id: prettier
#         types: [yaml]

# Editor integration:
# VS Code: install "YAML" extension (redhat)
#   + "yamllint" for inline linting
#   + schema validation via yaml-language-server

Структура и читаемость

Группируйте связанные ключи заголовками-комментариями. Держите вложенность неглубокой (максимум 3–4 уровня): глубоко вложенный YAML трудно читать. Используйте якоря для действительно переиспользуемых значений. Используйте блочные скаляры для многострочных строк. Держите строки короче 120 символов. Читаемость важна, потому что YAML редактируют люди.

yaml
# Group related keys; use comments to delineate sections
server:
  # Networking
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

  # Limits
  timeout: 30
  max_connections: 100
  retries: 3

# Keep nesting shallow (3-4 levels max)
# Deeply nested YAML is hard to read and edit.

# If a value is reused, use an anchor:
defaults: &defaults
  timeout: 30
  retries: 3

prod:
  <<: *defaults
  env: production

staging:
  <<: *defaults
  env: staging

# Use block scalars for multi-line values
script: |
  #!/bin/bash
  set -e
  echo "deploying"

# Keep lines under 120 chars; wrap with block scalars or
# multi-line flow style.
19

Продвинутые возможности

Сложные ключи отображений

Индикатор ? помечает сложный ключ (отображение или последовательность, используемые как ключ). Полезно для таблиц поиска (например, цены по региону и типу инстанса). Оговорка: многие сериализаторы не сохраняют сложные ключи и могут преобразовать их в строки при выводе. Большинство конфигов ограничивается простыми строковыми ключами ради простоты и совместимости с инструментами.

yaml
# Use ? to mark a complex (non-scalar) key
? apple
: red fruit

? orange
: orange fruit

# A mapping as a key
? host: localhost
  port: 8080
: connection_string

# A sequence as a key
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
? [us-west-2, t2.micro]
: 0.0125

# Useful for lookup tables
pricing:
  ? [production, large]
  : 100
  ? [production, small]
  : 50
  ? [development, large]
  : 20

# In flow style:
{[a, b]: value, {x: 1}: other}

# Caveat: many serializers don't preserve complex keys
# and may convert them to strings on output.

Множества (!!set)

YAML-множество (!!set) — отображение, где ключи являются элементами, а значения null. Некоторые парсеры отображают его в нативный тип Set. Используйте для объявления уникальных коллекций (роли, разрешения). Оговорка: в JSON нет типа Set, поэтому конвертация в JSON даёт объект со значениями null. Не все сериализаторы сохраняют тег !!set.

yaml
# A set is a mapping with null values
# Use the !!set tag for clarity
permissions: !!set
  ? read
  ? write
  ? execute

# Equivalent to:
permissions:
  read: null
  write: null
  execute: null

# Or in flow style:
flags: !!set { red, green, blue }

# Parsers may map this to a native Set type:
# Python: set() (PyYAML with !!set constructor)
# Ruby: Set (Psych)
# JavaScript: depends on library

# Use case: declare a unique collection
roles: !!set
  ? admin
  ? editor
  ? viewer

# Caveat: JSON has no Set type, so JSON conversion
# usually produces an object with null values.

Упорядоченные отображения (!!omap)

!!omap (упорядоченное отображение) — последовательность отображений с одним ключом, сохраняющая порядок вставки. Полезно для таймлайнов, упорядоченных предпочтений и случаев, где порядок семантически важен. Современные парсеры и так сохраняют порядок обычного отображения (Python dict 3.7+, Ruby Hash), но Go-словари случайны — !!omap делает порядок явным там.

yaml
# An ordered mapping preserves key order
# Use !!omap tag
timeline: !!omap
  - 2024-01-01: event A
  - 2024-02-01: event B
  - 2024-03-01: event C

# Equivalent representation as a list of single-key mappings:
# timeline:
#   - 2024-01-01: event A
#   - 2024-02-01: event B
#   - 2024-03-01: event C

# Parsers may map this to:
# Python: list of tuples, or OrderedDict
# Ruby: Array of one-key hashes (or OrderedDict)
# Go: ordered map (with custom type)

# Use case: ordered key-value pairs where order matters
# - event timelines
# - ordered preferences
# - step-by-step configurations

# Caveat: regular YAML mappings DO preserve order in
# most modern parsers (Python dict 3.7+, Ruby Hash,
# Go map iteration is random though). !!omap makes the
# intent explicit and works even where maps are unordered.

Бинарные данные (!!binary)

!!binary кодирует бинарные данные как base64 в YAML. Парсеры декодируют их в нативные байты (Python bytes, строка Ruby ASCII-8BIT). Полезно для встраивания небольших изображений или иконок напрямую. Для больших бинарных данных предпочитайте ссылку по пути или URL. Многострочный base64 работает с блочными скалярами > (folded) или | (literal).

yaml
# Encode binary data as base64 with !!binary tag
image: !!binary "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9
  awAAAABJRU5ErkJggg=="

# Multi-line base64 (folded or literal works)
data: !!binary |
  iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42m
  k+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==

# Parsers decode to bytes:
# Python: bytes object
# Ruby: ASCII-8BIT string
# JavaScript: depends on library (often base64 string)

# Use case: embed small images, icons, or other binary
# directly in YAML config

# For larger binary data, prefer:
# - Reference by path:  image: /path/to/image.png
# - Reference by URL:   image: https://example.com/img.png
# - Store separately and link

# Verify with:
# python -c 'import yaml; d=yaml.safe_load(open("f.yaml")); print(len(d["image"]))'

Свои конструкторы

Регистрируйте свои конструкторы, чтобы отображать теги (!money) в нативные объекты. Используйте add_constructor с загрузчиком, наследующим SafeLoader. Конструкторы получают загрузчик и узел; используйте construct_scalar/mapping/sequence для чтения значения узла. Всегда аудируйте конструкторы на побочные эффекты (чтение файлов, вызовы subprocess) — их можно эксплуатировать через недоверенный ввод.

yaml
# PyYAML: register a constructor for a custom tag
import yaml

class Money:
    def __init__(self, currency, amount):
        self.currency = currency
        self.amount = amount
    def __repr__(self):
        return f"Money({self.currency} {self.amount})"

def money_constructor(loader, node):
    value = loader.construct_scalar(node)  # "USD 19.99"
    currency, amount = value.split()
    return Money(currency, float(amount))

# Register the constructor (use SafeLoader scope)
yaml.add_constructor('!money', money_constructor, Loader=yaml.SafeLoader)

# Now this YAML parses to a Money object:
# price: !money "USD 19.99"
config = yaml.safe_load("price: !money \"USD 19.99\"")
print(config['price'])  # Money(USD 19.99)

# Multi-argument constructors use construct_mapping or
# construct_sequence depending on the node kind.

# SECURITY: audit every constructor for side effects.
# A constructor that calls open(), os.system(), or
# subprocess can be exploited via untrusted input.

Возможности YAML 1.2 и будущее

YAML 1.2 сделал JSON строгим подмножеством, ограничил boolean true/false и принял 0o для восьмеричных. Merge key << удалён из ядра спецификации, но всё ещё широко поддерживается. YAML 1.2.2 (2021) уточнил спецификацию; 1.3 в разработке. Защищайтесь от будущего фиксацией версии, закавычиванием неоднозначных строк и рассмотрением Cue/Dhall/Jsonnet для сложных конфигов.

yaml
# YAML 1.2 (2009, current spec) key changes from 1.1:
# - JSON is a strict subset
# - Booleans: only true/false (not yes/no/on/off)
# - Octal: 0o prefix (not leading 0)
# - Removed sexagesimal numbers
# - Removed merge key << from core spec (still widely supported)

# YAML 1.3 (in development) aims to:
# - Clarify ambiguous parts of 1.2
# - Standardize error reporting
# - Improve interoperability between parsers
# - Possibly restore some 1.1 features as optional

# YAML 1.2.2 (2021 update, spec revision):
# - Clarified type resolution
# - Better-defined core schema
# - Improved examples
# - No breaking changes

# Recommended practices for future-proofing:
# 1. Pin %YAML 1.2 in critical files
# 2. Quote ambiguous strings (yes/no, leading-zero numbers)
# 3. Avoid relying on << merge key for new formats
#    (or document that you depend on it)
# 4. Use JSON-compatible subset when interop matters
# 5. Watch for YAML 1.3 adoption in your parser

# Some tools (Cue, Dhall, Jsonnet) extend/replace YAML
# for complex configuration — consider them for new
# projects with advanced needs.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.