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

> Сравнить JSON и YAML: синтаксис, комментарии, якоря, проблема Норвегии в YAML 1.1 и 1.2, числа. JSON или YAML — что выбрать для API и конфигов.

- Адрес: https://jsonstatham.dev/ru/guides/json-vs-yaml/
- Язык: Русский (ru)
- Английская версия: https://jsonstatham.dev/guides/json-vs-yaml.md
- Обновлено: 2026-11-08

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

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

```json
{
  "service": "billing",
  "replicas": 3,
  "debug": false,
  "regions": ["eu-west-1", "us-east-1"],
  "db": { "host": "db.internal", "port": 5432 }
}
```

```yaml
# сервис биллинга
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](https://jsonstatham.dev/ru/guides/json-comments/)). При переводе YAML в JSON комментарии пропадают. Ещё YAML умеет переиспользовать блок:

```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. Одни и те же значения без кавычек у трёх из них:

```yaml
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](https://jsonstatham.dev/ru/guides/json-big-numbers/).

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

[Конвертер JSON в YAML](https://jsonstatham.dev/ru/json-to-yaml/) пишет строку без кавычек, только если ни один читатель YAML 1.1 или 1.2 не поймёт её иначе. В кавычки попадают слова yes, no, on, off, y, n, true, false, null и `~` в любом регистре; строки, которые начинаются с цифры, `+`, `.` или служебного символа YAML вроде `-`, `[`, `&` и `*`; пустые строки; строки с пробелом в начале или в конце, с `: ` или ` #` внутри. Многострочные строки становятся блоками `|`. Числа переносятся ровно в той записи, что в JSON, порядок ключей сохраняется. Вот такой 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"}
```

```yaml
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](https://jsonstatham.dev/ru/yaml-to-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`. Отступы — пробелами. Внутри строк в кавычках табы допустимы.
