Что такое YAML — формат, в котором Норвегия превращается в false

Есть известная история, её называют «проблемой Норвегии». Человек составлял список стран в YAML-файле:

countries:
  - DE
  - FR
  - NO

Германия и Франция загрузились как строки "DE" и "FR". А Норвегия — как false. Не строка «NO», а буквально логическое «нет». Потому что в классическом YAML слова no, yes, on, off — это способы записать true и false, и парсер честно так их и понял.

Вот это и есть YAML в двух словах: формат, который выглядит настолько просто, что его хочется писать без правил, — и у которого правила при этом есть, причём с сюрпризами. Давай разберёмся, как читать его уверенно.

Где ты его встретишь

YAML — стандартный формат конфигов: файлов с настройками, которые пишет человек, а читает программа. Открой почти любой проект на GitHub — увидишь .yml-файлы: настройки CI/CD в .github/workflows/, docker-compose.yml, конфиги деплоя. Даже шапка-frontmatter в Markdown-файлах — это YAML.

То есть ты будешь не столько писать YAML с нуля, сколько править готовый: поменять версию, добавить шаг, вписать своё имя переменной. Для этого хватает трёх строительных блоков.

Три блока, из которых состоит любой YAML

Пара «ключ: значение» — основа основ:

name: kodiq-app
port: 3000
debug: true

Вложенность через отступы. Здесь главное отличие от JSON: никаких фигурных скобок — что внутри чего, показывают два пробела отступа:

server:
  host: localhost
  port: 3000

host и port сдвинуты вправо — значит, они «внутри» server. Отступ — это не оформление, это синтаксис. Сдвинешь строку на один пробел — изменится смысл файла или всё упадёт с ошибкой. Поэтому правило простое: всегда два пробела, никогда табы (таб в YAML запрещён).

Списки через дефис:

steps:
  - install
  - build
  - deploy

Всё. Этих трёх блоков хватает, чтобы прочитать 95% конфигов, которые тебе встретятся.

Правила выживания

Четыре привычки, которые закрывают почти все грабли:

• Строки с сюрпризом бери в кавычки. NO, yes, off, версия 3.10 (без кавычек станет числом 3.1!), время 08:30, что угодно с двоеточием внутри. Сомневаешься — кавычки не повредят: country: "NO" всегда строка.
• Только пробелы, всегда по два. Настрой редактор, чтобы таб вставлял пробелы, — и половина проблем исчезнет.
• После двоеточия — пробел. port: 3000 работает, port:3000 — нет.
• Сломалось непонятно где — прогони через валидатор. ИИ-ассистенту можно просто вставить файл и спросить «где ошибка в этом YAML» — найдёт съехавший отступ быстрее, чем глаза.

И отдельно про «проблему Норвегии»: в современном стандарте YAML 1.2 голое no уже честная строка, но многие популярные парсеры до сих пор живут по старым правилам. Поэтому не выясняй, повезёт ли, — просто ставь кавычки.

Почему не JSON, если он строже?

Логичный вопрос: у JSON правила жёстче, сюрпризов меньше — почему конфиги не пишут на нём? Потому что JSON не умеет главного для конфигов: комментариев. Строчка # это выключено до релиза в JSON невозможна. Плюс YAML избавлен от шума скобок и запятых — файл, который человек правит руками раз в неделю, приятнее читать без них.

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

Что значит расширение .yml и .yaml?

Это один и тот же формат, просто два варианта расширения. Официально рекомендуют .yaml, но исторически многие инструменты (например, GitHub Actions) используют .yml. Работают оба.

Почему мой YAML не читается, хотя выглядит нормально?

В 9 случаях из 10 — отступы: где-то затесался таб вместо пробелов или строка съехала на один пробел. Включи в редакторе отображение невидимых символов или скорми файл валидатору — ошибка найдётся мгновенно.

YAML нужно учить специально?

Нет. Три блока из этой статьи + правила выживания — всё, что нужно новичку. Дальше он учится сам: каждый раз, когда правишь чужой конфиг, ты его уже читаешь.