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| Что | JSON | YAML |
|---|---|---|
| Структура | Фигурные и квадратные скобки, запятые | Отступы пробелами или скобки {} и [], как в 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) |
|---|---|---|---|
NO | False | false | "NO" |
on как ключ | True | true | "on" |
3.10 | 3.1 | 3.1 | 3.1 |
0123 | 83 | 83 | 83 |
12:30 | 750 | 45000 | "12:30" |
1e3 | "1e3" | "1e3" | 1000 |
2026-11-06 | дата | Date | time.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. Отступы — пробелами. Внутри строк в кавычках табы допустимы.