YAML

Два формата, пересекающиеся задачи

JSON (JavaScript Object Notation) и YAML (YAML Ain’t Markup Language) оба представляют структурированные данные: вложенные объекты, списки, строки, числа и булевы значения. Они встречаются в API, файлах конфигурации, CI-пайплайнах, манифестах Kubernetes и примерах документации. Выбор между ними — не столько вопрос «что лучше», сколько кто редактирует файл, какие инструменты его потребляют и насколько строгим должен быть разбор.

Если у вас уже есть JSON и вы хотите посмотреть его как YAML с отступами, конвертируйте через JSON в YAML.

JSON кратко

JSON вырос из синтаксиса литералов объектов JavaScript и стал языконезависимым форматом обмена. Документ JSON строится из:

• Объектов: { "key": "value" }
• Массивов: [1, 2, 3]
• Строк в двойных кавычках
• Чисел
• true, false и null

Важные ограничения: нет комментариев, нет завершающих запятых в стандартном JSON, ключи должны быть строками, а строки используют ограниченный escape-синтаксис. Эти ограничения делают парсеры простыми и строгими—ценно для машин, обменивающихся данными.

Красиво отформатированный JSON читаем для небольших документов. Большие конфиги с глубокой вложенностью становятся шумными из‑за скобок, квадратных скобок и кавычек вокруг ключей в каждой строке.

YAML кратко

YAML делает акцент на правке человеком. Структура в основном передаётся отступами, а не скобками. Возможности включают:

• Комментарии, начинающиеся с #
• Незакавыченные строки во многих случаях
• Anchors и aliases для повторного использования
• Несколько потоков документов, разделённых ---
• Явные type tags в продвинутом использовании

Небольшой mapping выглядит так:

service:
  name: api
  replicas: 3
  ports:
    - 8080
    - 8443

Та же структура в JSON повторяет пунктуацию и кавычки. Для операторов, ежедневно правящих манифесты, краткость YAML привлекательна.

Пересечение модели данных

В основе оба формата могут выражать деревья map и последовательностей со скалярными листьями. Round-trip часто возможен для общего подмножества: объекты, массивы, строки, числа, булевы значения и null.

Различия проявляются на краях:

• YAML может давать нестроковые ключи; JSON — нет.
• У YAML больше способов записи строк (literal blocks, folded blocks).
• «Norway problem» в YAML и другие особенности неявной типизации могут превратить незакавыченные NO, on или токены, похожие на версии, в булевы или числа в зависимости от версии YAML и парсера.
• Числа JSON прямолинейны; YAML в некоторых loader может особо разбирать большие целые или timestamps.

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

Комментарии и документация

В JSON нет стандартных комментариев. Команды иногда злоупотребляют полями "_comment", засоряя schemas. Комментарии # в YAML документируют намерение рядом с данными—почему число реплик равно 3, какая команда владеет label—не меняя информационную модель.

Если основная аудитория — машины (API, тела fetch в браузере), отсутствие комментариев в JSON редко проблема. Если люди поддерживают файл месяцами, комментарии YAML снижают потерю «племенного» знания.

Инструменты и экосистема

Сильные стороны JSON

• Повсеместные парсеры почти в каждом mainstream-языке
• Поддержка браузера первого класса (JSON.parse / JSON.stringify)
• Широко принятые экосистемы схем (JSON Schema)
• Построчные diffs, которые, хоть и богаты скобками, привычны
• Streaming-парсеры для больших payload

Сильные стороны YAML

• Доминирует в DevOps (Kubernetes, Ansible, многие CI-системы)
• Merges и anchors (мощно, иногда избыточно)
• Multi-document файлы для объединения связанных ресурсов
• Удобнее для слабо вложенной конфигурации

Риски YAML

• Сложность спецификации (различия YAML 1.1 vs 1.2)
• Ошибки отступов, которые трудно заметить
• Возможности (custom tags, merge keys), снижающие переносимость
• Исторически случайное выполнение кода в небезопасных loader—всегда используйте safe load API

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

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

Бинарные «родственники» (MessagePack, CBOR, Protobuf) превосходят оба, когда доминирует throughput. Это не drop-in форматы для людей.

Стратегии конвертации

Преобразование JSON → YAML для общего подмножества обычно без потерь и полезно для обзоров читаемости. Преобразование YAML → JSON может потерять комментарии, anchors и типы, не входящие в JSON. Считайте конвертацию проекцией, а не идеальным архивом авторского намерения.

Советы по workflow:

1. Держите единственный источник истины (часто JSON Schema или типизированная модель языка).
2. Генерируйте формат, нужный каждому потребителю.
3. Если люди должны править YAML, валидируйте по схеме при каждом изменении.
4. Избегайте ручного ведения двух копий одного документа.

Конвертер from-json на Tool Plaza помогает увидеть, как JSON payload выглядит с синтаксисом на основе отступов.

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

• Публичные HTTP API и тела webhook
• Браузерные и мобильные клиенты
• Строгий машинный обмен с минимальной неоднозначностью
• Логирование структурированных событий в агрегаторы, ожидающие JSON lines
• Встраивание в языки, где литералы JSON чисто отображаются на нативные типы

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

• Манифесты развёртывания и инфраструктуры, которые правят люди
• Конфиги, которым полезны комментарии
• Экосистемы, уже стандартизированные на YAML
• Документы, где ясность отступов важнее сопоставления скобок для вашей команды

Гибридные подходы

Некоторые проекты хранят канонический JSON в системе контроля версий и генерируют YAML для конкретного инструмента. Другие принимают YAML-вход, нормализуют во внутренний AST и отдают JSON для API. Оба подхода работают, если пайплайн автоматизирован и протестирован.

Будьте осторожны с расширениями «JSON5» или «JSONC» (JSON с комментариями): они улучшают эргономику, но не универсальны. Документируйте диалект, если его принимаете.

Гигиена правки и ревью

• Используйте редакторы, подсвечивающие отступы и хвостовые пробелы в YAML.
• Падайте в CI при невалидном синтаксисе до merge.
• Предпочитайте единообразные отступы в 2 пробела в YAML-командах.
• Держите строки разумно короткими; огромные inline-строки относятся к literal blocks или внешним файлам.
• Не вставляйте секреты ни в один формат в публичных репозиториях—используйте secret managers и ссылки.

Итог

JSON — строгий, повсеместный формат обмена; YAML — дружелюбный к комментариям конфигурационный диалект с более богатым—и более рискованным—синтаксисом. Для повседневных map и списков они разделяют вложенную модель данных. Выбирайте JSON для API и машин, YAML для infra-файлов, которыми оперируют люди, и конвертируйте осознанно, когда нужны оба представления одной структуры.