ENRU

JSON или YAML: разница, ловушки и что выбрать

Обновлено

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

Одни и те же данные в JSON и YAML

{
  "service": "billing",
  "replicas": 3,
  "debug": false,
  "regions": ["eu-west-1", "us-east-1"],
  "db": { "host": "db.internal", "port": 5432 }
}
# сервис биллинга
service: billing
replicas: 3
debug: false
regions:
  - eu-west-1
  - us-east-1
db:
  host: db.internal
  port: 5432
ЧтоJSONYAML
СтруктураФигурные и квадратные скобки, запятыеОтступы пробелами или скобки {} и [], как в JSON
СтрокиВсегда в двойных кавычкахБез кавычек, в одинарных, в двойных или блоком | и >
КомментарииНет# до конца строки
Повторное использованиеНетЯкоря &, ссылки *, ключ слияния <<
Несколько документовОдно значение на текстЧерез ---
ТипыШесть, задаются синтаксисомУгадываются по тексту без кавычек; 1.1 и 1.2 угадывают по-разному
СпецификацияRFC 8259, одна версияYAML 1.1 (2005), 1.2 (2009, редакция 1.2.2 — 2021)

Комментарии, якоря и несколько документов

В YAML есть комментарии #; в JSON их нет, и любой обходной путь — договорённость (комментарии в JSON). При переводе YAML в JSON комментарии пропадают. Ещё YAML умеет переиспользовать блок:

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

&defaults даёт блоку имя, *defaults ссылается на него, а << вливает его ключи, так что production становится {"timeout": 60, "retries": 3}. Ключ слияния пришёл из списка типов YAML 1.1 и в YAML 1.2 не входит, но PyYAML, Psych и go-yaml v3 его понимают. Ссылок в JSON нет: каждая ссылка превращается в полную копию, поэтому конвертеры ограничивают, насколько ссылки могут раздуться. Ещё в одном файле YAML может быть несколько документов через ---, как часто бывает с манифестами Kubernetes; текст JSON — одно значение.

Проблема Норвегии: YAML 1.1 и 1.2

В YAML 1.1 yes, no, on и off без кавычек, в любом написании, — булевы значения. Поэтому список кодов стран [GB, NO, SE] читается как ["GB", false, "SE"]: Норвегия превращается в false (отсюда название — Norway problem). YAML 1.2 оставил из булевых только true и false, но многие популярные библиотеки до сих пор реализуют 1.1. Одни и те же значения без кавычек у трёх из них:

country: NO
on: push
python: 3.10
zip: 0123
time: 12:30
exp: 1e3
date: 2026-11-06
Без кавычекPyYAML 6.0.3 (1.1)Ruby Psych 3.1 (1.1)go-yaml v3 (1.2)
NOFalsefalse"NO"
on как ключTruetrue"on"
3.103.13.13.1
0123838383
12:3075045000"12:30"
1e3"1e3""1e3"1000
2026-11-06датаDatetime.Time

Выводов три. YAML 1.2 исправил булевы, но не всё: go-yaml v3 всё ещё читает 0123 как восьмеричное 83, а даты — как метки времени. Библиотеки одной версии расходятся между собой: 12:30 в PyYAML — 750, в Psych — 45000. А файл GitHub Actions, прочитанный через PyYAML, получает ключ True вместо on. Правило, которое работает с любым читателем: если строка может сойти за что-то другое, бери её в кавычки.

Числа в JSON и YAML

У числа JSON одна запись: необязательный минус, цифры без ведущего нуля, необязательные дробная часть и экспонента. Ни +, ни шестнадцатеричных, ни NaN и Infinity. Точность RFC 8259 оставляет читателю и лишь предупреждает: за пределами 64-битного double совместимость не гарантирована. YAML 1.2 добавляет 0o17, 0x1F, .inf и .nan; YAML 1.1 — ещё 0b1010, 1_000, шестидесятеричное 1:30 и восьмеричное 017. В обоих форматах загруженная дробь теряет нули в конце (1.10 становится 1.1), а большие целые выживают, только если их держит язык: см. статью о больших числах в JSON.

Как наш JSON в YAML сохраняет значения

Конвертер JSON в YAML пишет строку без кавычек, только если ни один читатель YAML 1.1 или 1.2 не поймёт её иначе. В кавычки попадают слова yes, no, on, off, y, n, true, false, null и ~ в любом регистре; строки, которые начинаются с цифры, +, . или служебного символа YAML вроде -, [, & и *; пустые строки; строки с пробелом в начале или в конце, с : или # внутри. Многострочные строки становятся блоками |. Числа переносятся ровно в той записи, что в JSON, порядок ключей сохраняется. Вот такой JSON:

{"country": "NO", "enabled": "on", "python": "3.10", "zip": "0123",
 "time": "12:30", "date": "2026-11-06", "version": 3.10, "exp": 1e3,
 "note": "line one\nline two", "plain": "hello world"}
country: "NO"
enabled: "on"
python: "3.10"
zip: "0123"
time: "12:30"
date: "2026-11-06"
version: 3.10
exp: 1e3
note: |-
  line one
  line two
plain: hello world

Одна оговорка, прямо: числа сохраняют запись из JSON, поэтому 1e3 остаётся 1e3. Читатель YAML 1.2 увидит число 1000, а читатель YAML 1.1 вроде PyYAML или Psych — строку "1e3": в 1.1 дробному числу нужна точка. Обратное направление — YAML в JSON: он читает YAML по правилам 1.2, так что no без кавычек остаётся строкой "no".

Когда выбирать JSON, а когда YAML

  • JSON — для данных между программами: запросы и ответы API, логи, хранение, сгенерированные файлы. Парсер есть почти в каждом языке из коробки, а строгий валидатор ловит любую опечатку.
  • JSON — когда значения должны дойти точно. Неявных типов нет: "no" всегда строка, а "0123" всегда с нулём.
  • YAML — для файлов, которые пишут и читают люди: манифесты Kubernetes, CI-пайплайны, Docker Compose, спецификации OpenAPI. Там комментарии, многострочные строки и якоря окупаются.
  • YAML — с дисциплиной: строки, похожие на булевы, числа и даты, в кавычки; отступы только пробелами; чужие файлы грузить безопасным загрузчиком (yaml.safe_load в Python, а не yaml.load).

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

Частые вопросы: JSON или YAML

JSON — это валидный YAML?

Для YAML 1.2 почти всегда: спецификация нарочно сделала JSON подмножеством. Исключения — повторы ключей, которые YAML запрещает (go-yaml v3 падает с mapping key "a" already defined, PyYAML оставляет последнее значение), и экран \/, который go-yaml v3 не принимает.

Почему YAML читает no как false?

Библиотека читает YAML по версии 1.1, где yes, no, on и off — булевы. Возьми значение в кавычки ("NO") или перейди на читатель YAML 1.2.

Что происходит с комментариями и якорями при переводе YAML в JSON?

Комментарии пропадают: в JSON для них нет места. Каждая ссылка разворачивается в полную копию, а ключи слияния << становятся обычными ключами.

Можно ли делать отступы в YAML табами?

Нет. YAML запрещает табы в отступах; PyYAML останавливается с found character '\t' that cannot start any token. Отступы — пробелами. Внутри строк в кавычках табы допустимы.