JSON vs YAML: Differences, Pros & Cons (With Examples)

Both formats represent the same data, but they make very different trade-offs. Here's how to decide which one fits your use case.

Команда JSONTechFebruary 10, 20259 min read

Краткий ответ

Используйте JSON, когда основными пользователями являются машины — API, обмен данными, все, что парсится программно. Используйте YAML, когда основными пользователями являются люди — конфигурационные файлы, CI/CD пайплайны, все, что редактируется вручную. Это общее правило, и оно работает примерно в 90% случаев.

Но если вы хотите получить полное представление — с реальными компромиссами, подводными камнями и нюансами, которые действительно имеют значение в производстве — продолжайте читать.

Сравнение синтаксиса

Начнем с одних и тех же данных, представленных в обоих форматах. Это типичная конфигурация для веб-приложения:

JSON

{
  "server": {
    "host": "0.0.0.0",
    "port": 3000,
    "ssl": true
  },
  "database": {
    "driver": "postgres",
    "host": "db.example.com",
    "port": 5432,
    "credentials": {
      "username": "app_user",
      "password": "s3cret"
    },
    "pools": [5, 10, 20]
  },
  "features": {
    "darkMode": true,
    "betaAccess": false,
    "maxUploadSizeMB": 25
  }
}

YAML

# Конфигурация сервера
server:
  host: "0.0.0.0"
  port: 3000
  ssl: true

# Настройки базы данных
database:
  driver: postgres
  host: db.example.com
  port: 5432
  credentials:
    username: app_user
    password: s3cret
  pools:
    - 5
    - 10
    - 20

# Флаги функций
features:
  darkMode: true
  betaAccess: false
  maxUploadSizeMB: 25

Версия YAML короче, содержит комментарии, объясняющие каждую секцию, и читается почти как маркированный список. Версия JSON более явная — каждая строка заключена в кавычки, структура определяется фигурными и квадратными скобками, и нет никакой неоднозначности в отношении типов.

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

Мгновенно конвертируйте между форматами: Вставьте JSON в наш конвертер JSON в YAML, чтобы увидеть эквивалент YAML рядом. Или сделайте обратное с YAML в JSON.

Сравнение функций

Функция	JSON	YAML
Читаемость для человека	Хорошо (с форматированием)	Отлично
Поддержка комментариев	❌ Нет	✅ Да (синтаксис `#`)
Размер файла	Больше (кавычки + фигурные скобки)	Меньше (основан на отступах)
Скорость парсинга	Очень быстро	Медленнее (более сложная грамматика)
Дружественность для машин	Отлично	Хорошо
Ручное редактирование	Умеренно (легко пропустить запятые)	Легко (но чувствительно к отступам)
Чувствительность к отступам	Нет (пробелы игнорируются)	Да (отступы определяют структуру)
Многострочные строки	Нет (используйте `\n` экранирования)	Да (операторы pipe `
Якоря и алиасы	Нет	Да (DRY с `&` и `*`)
Нативные типы данных	6 типов (строка, число, булев, null, объект, массив)	Все типы JSON + даты, временные метки, бинарные
Сложность спецификации	~10 страниц	~80 страниц
Поддержка браузерами	Нативная (`JSON.parse`)	Требует библиотеки (js-yaml, yaml)

Когда использовать JSON

JSON является лучшим выбором, когда данные обмениваются между системами, а не читаются людьми. В частности:

API и обмен данными

Каждый крупный REST API использует JSON. Ответы GraphQL — это JSON. Поля вебхуков — это JSON. Вся веб-экосистема построена вокруг Content-Type: application/json. Использование YAML для ответов API было бы против течения.

package.json и Lockfiles

npm, Yarn и большинство инструментов JavaScript используют JSON для своих конфигурационных и lock-файлов. Спецификация package.json требует строгого JSON. Вы не можете добавлять комментарии (хотя есть известный хак с использованием ключа "//"), и вы не можете использовать завершающие запятые. Это раздражает, но это стандарт.

{
  "name": "my-app",
  "version": "2.1.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^15.0.0",
    "react": "^19.0.0"
  }
}

Везде, где нужна скорость

Парсеры JSON работают очень быстро, потому что грамматика проста. Если вы обрабатываете миллионы сообщений в конвейере, преимущество производительности парсинга JSON по сравнению с YAML значительно. Мы говорим о 5-10 раз быстрее в большинстве бенчмарков.

Когда использовать YAML

YAML выделяется, когда люди пишут и поддерживают файлы. Мир DevOps в значительной степени стандартизировался на YAML, и на то есть веские причины.

Docker Compose

version: "3.8"
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

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

Манифесты Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

Файлы YAML для Kubernetes могут быть огромными. Без комментариев и чистой структуры на основе отступов их было бы невозможно поддерживать. Тем не менее, даже с YAML большие конфигурации K8s все еще довольно болезненны — именно поэтому существуют такие инструменты, как Helm и Kustomize.

CI/CD пайплайны

GitHub Actions, GitLab CI, CircleCI и большинство CI платформ используют YAML для определения пайплайнов. Возможность добавлять встроенные комментарии, объясняющие почему существует тот или иной шаг, стоит своего веса в золоте, когда вы отлаживаете сбой сборки в 2 часа ночи.

Общие подводные камни

Подводные камни YAML

Проблема Норвегии: В YAML 1.1 NO интерпретируется как булевое false. Кодовые обозначения стран, аббревиатуры и другие короткие строки могут быть тихо неправильно интерпретированы. YAML 1.2 исправил это, но некоторые парсеры все еще используют старую спецификацию. Всегда заключайте строки, которые могут быть неоднозначными, в кавычки.
Ошибки отступов без предупреждения: Неправильный уровень отступа не всегда вызывает ошибку парсинга — он может просто создать другую структуру, чем вы намеревались. Это главный источник ошибок YAML в моем опыте.
Запрещены символы табуляции: YAML допускает только пробелы для отступов. Если вы смешаете табуляцию, вы получите загадочную ошибку парсинга.
Проблемы безопасности: Тег !!python/object в YAML (и подобные) может выполнять произвольный код во время парсинга. Всегда используйте безопасные функции загрузки.

Подводные камни JSON

Нет комментариев. Вы будете их скучать. Все их скучают. Некоторые инструменты поддерживают JSONC, но стандартный JSON этого не делает.
Ловушка завершающей запятой: JavaScript позволяет их использовать. JSON — нет. Копирование и вставка между ними будет регулярно вас подводить.
Точность чисел: Числа JSON — это IEEE 754 двойные. Большие целые числа (более 2^53) теряют точность. Если вы имеете дело с большими идентификаторами, передавайте их как строки.
Нет многострочных строк: Длинные текстовые значения требуют экранирования \n, что делает файл труднее читаемым.

Попробуйте сами: Преобразуйте сложный JSON файл в YAML с помощью нашего конвертера JSON в YAML и посмотрите, как структура сопоставляется между форматами. Или сначала проверьте ваш JSON с помощью JSON Validator.

Можно ли использовать оба?

Абсолютно, и большинство проектов это делает. Типичный проект Node.js может иметь package.json (JSON) наряду с docker-compose.yml (YAML) и .github/workflows/ci.yml (YAML). Нет ничего плохого в смешивании форматов — используйте тот, который ожидает инструмент, или тот, который имеет больше смысла для контекста.

Одно важное замечание: YAML является надмножеством JSON (по состоянию на YAML 1.2). Это означает, что каждый действительный документ JSON также является действительным YAML. Так что если вы вставите JSON в парсер YAML, это сработает. Обратное неверно — у YAML есть функции, которые JSON не поддерживает.

Сравнение производительности

Если производительность важна для вашего случая, JSON однозначно выигрывает. Вот приблизительные цифры по парсингу одного и того же документа размером 1 МБ:

Операция	JSON	YAML
Время парсинга (Node.js)	~15ms	~120ms
Время сериализации	~10ms	~80ms
Размер файла (отформатированный)	1.00 MB	0.75 MB
Размер файла (минифицированный)	0.60 MB	N/A (YAML нельзя действительно минифицировать)

Файлы YAML меньше, потому что они пропускают кавычки и фигурные скобки, но их парсинг занимает значительно больше времени. Для конфигурационных файлов, читаемых один раз при запуске, это не имеет значения. Для API-пayload, обрабатываемых миллионы раз в день, это имеет большое значение.

Итог

Я рекомендую JSON в качестве стандартного выбора для обмена данными и YAML для конфигурации. Если инструмент предоставляет вам выбор, подумайте о том, кто будет читать и редактировать файл. Машины? JSON. Люди? YAML. Оба? Начните с JSON и посмотрите, не подтолкнет ли вас отсутствие комментариев к YAML.

И если вы новичок в JSON, начните с нашего Что такое JSON? руководства для изучения основ.

Связанные инструменты:

Конвертер JSON в YAML
Конвертер YAML в JSON
Форматировщик JSON
JSON против XML — еще одно сравнение распространенных форматов