YAML и JSON: различия, конвертация и лучшие практики

YAML и JSON — два самых распространённых формата для конфигураций и обмена данными в современной разработке. Docker Compose, манифесты Kubernetes, настройки CI/CD — всё это чаще всего пишется в YAML. REST API, конфиги приложений и хранилища данных — в JSON. Понимание различий, умение выбирать формат под задачу и конвертировать между ними — базовые навыки для DevOps и backend-разработчиков. В этой статье разберём синтаксис обоих форматов, сравним их по ключевым критериям, рассмотрим практические примеры, методы конвертации и типичные ошибки.

Что такое YAML

YAML (YAML Ain't Markup Language) — формат сериализации данных, ориентированный на читаемость человеком. Появился в 2001 году как альтернатива XML. Основные особенности:

• Отступы вместо скобок — структура задаётся пробелами (табуляция не рекомендуется)
• Минимум синтаксиса — нет лишних кавычек и запятых
• Комментарии — поддерживаются через #
• Мультистроки — удобный синтаксис для длинного текста
• Анкоры и алиасы — переиспользование фрагментов

# Пример конфигурации
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret
  replicas:
    - primary
    - standby

Что такое JSON

JSON (JavaScript Object Notation) — компактный формат обмена данными, основанный на подмножестве синтаксиса JavaScript. Стандартизирован в RFC 8259. Основные особенности:

• Строгий синтаксис — все ключи в кавычках, запятые обязательны
• Нет комментариев — формат не поддерживает комментарии
• Ограниченный набор типов — объекты, массивы, строки, числа, true/false, null
• Универсальность — нативная поддержка во всех языках и браузерах

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "user": "admin",
      "password": "secret"
    },
    "replicas": ["primary", "standby"]
  }
}

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

Элемент	YAML	JSON
Объект	key: value с отступами	"key": "value" в фигурных скобках
Массив	- item или [a, b, c]	["a", "b", "c"]
Строка	Без кавычек или в кавычках	Всегда в двойных кавычках
Число	42, 3.14	42, 3.14
Булево	true, yes, on	Только true или false
Null	null, ~, пустое значение	null
Комментарии	# комментарий	Не поддерживаются

Один и тот же фрагмент в обоих форматах

YAML:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: debug
  FEATURES:
    - auth
    - caching

JSON:

{
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "app-config"
  },
  "data": {
    "LOG_LEVEL": "debug",
    "FEATURES": ["auth", "caching"]
  }
}

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

Критерий	YAML	JSON
Читаемость	Выше — меньше визуального шума	Ниже — много кавычек и скобок
Компактность	Обычно компактнее для конфигов	Больше символов на ту же структуру
Комментарии	Поддерживаются	Нет
Стандартизация	Спецификация, но много нюансов	Строгий RFC 8259
Парсинг	Сложнее, чувствителен к отступам	Проще, однозначный разбор
API	Редко	Де-факто стандарт для REST
Конфиги	Docker, K8s, CI/CD, Ansible	package.json, tsconfig, многие приложения

Рекомендации:

• YAML — конфигурации, которые часто читают и правят люди: Docker Compose, Kubernetes, GitHub Actions, GitLab CI, Ansible playbooks. Поддержка комментариев позволяет документировать настройки прямо в файле.
• JSON — API-ответы, обмен данными между сервисами, конфиги, которые генерируются или потребляются кодом (package.json, настройки IDE). Строгая спецификация и нативная поддержка в JavaScript делают JSON идеальным для веб-приложений.

Практические примеры

Docker Compose

Типичный docker-compose.yml:

version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    environment:
      - NODE_ENV=production
    volumes:
      - ./data:/app/data
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret

Эквивалент в JSON (Docker Compose поддерживает и .json):

{
  "version": "3.8",
  "services": {
    "web": {
      "image": "nginx:alpine",
      "ports": ["80:80"],
      "environment": ["NODE_ENV=production"],
      "volumes": ["./data:/app/data"]
    },
    "db": {
      "image": "postgres:15",
      "environment": {
        "POSTGRES_USER": "app",
        "POSTGRES_PASSWORD": "secret"
      }
    }
  }
}

Манифест Kubernetes

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

В JSON манифесты K8s выглядят громоздко, поэтому на практике почти всегда используют YAML. Конвертация полезна при генерации манифестов из кода (например, через client-go), при отладке API Kubernetes или при миграции конфигов между системами.

GitHub Actions

name: CI
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

CI/CD-конфиги (GitHub Actions, GitLab CI, CircleCI) почти всегда пишутся в YAML из-за читаемости и поддержки комментариев. При необходимости интеграции с системами, ожидающими JSON, конвертация занимает секунды.

Конвертация YAML ↔ JSON

Онлайн-конвертер reChecker

Для быстрой конвертации без написания кода используйте онлайн-конвертер YAML ↔ JSON. Сервис позволяет:

• YAML → JSON — вставить YAML, получить валидный JSON с правильной структурой
• JSON → YAML — преобразовать JSON в читаемый YAML с корректными отступами
• Валидация — проверка синтаксиса обоих форматов
• Безопасность — все операции выполняются в браузере, данные не отправляются на сервер

Инструмент подходит для разовых преобразований, отладки конфигов и быстрой проверки структуры. Работа в браузере означает, что чувствительные данные (пароли, ключи API) не покидают вашу машину. Для сложных YAML с мультистроками, анкорами и кастомными тегами используйте специализированные библиотеки вроде js-yaml или PyYAML.

Программная конвертация

Node.js (js-yaml):

const yaml = require('js-yaml');

const yamlStr = `
database:
  host: localhost
  port: 5432
`;
const obj = yaml.load(yamlStr);
const jsonStr = JSON.stringify(obj, null, 2);

// Обратно: JSON → YAML
const yamlOut = yaml.dump(JSON.parse(jsonStr));

Python (PyYAML):

import yaml
import json

with open('config.yaml') as f:
    data = yaml.safe_load(f)

with open('config.json', 'w') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# Обратно
with open('config.json') as f:
    data = json.load(f)
with open('config.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False, allow_unicode=True)

Типичные ошибки

YAML

1. Смешение табуляции и пробелов — YAML допускает только пробелы для отступов. Табуляция приведёт к ошибке парсинга.
2. Неверные отступы — вложенность должна быть строго на 2 (или 4) пробела. Лишний или недостающий пробел ломает структуру.
3. Ложное определение типа — yes, no, on, off интерпретируются как булевы. Для строки используйте кавычки: "yes".
4. Числа с ведущими нулями — 0123 может быть распознано как восьмеричное. Для строки: "0123".

JSON

1. Запятая в конце — {"a": 1,} невалиден в строгом JSON (хотя допустимо в JavaScript).
2. Неэкранированные символы — в строках экранируйте ", \, переносы строк (\n), табуляцию (\t).
3. Некавыченные ключи — {key: "value"} невалиден, нужно {"key": "value"}.
4. Trailing comma — запятая после последнего элемента массива или объекта вызывает ошибку.

Валидация

Перед конвертацией или использованием конфига проверьте его на валидность:

• JSON — JSON Formatter или JSON.parse() в консоли браузера
• YAML — YAML ↔ JSON конвертер покажет ошибки при разборе; для сложных файлов — yamllint в CLI

При автоматизации добавьте валидацию в CI: невалидный конфиг должен падать на этапе сборки, а не в рантайме.

Лучшие практики

• Единый стиль отступов — в YAML используйте 2 пробела (рекомендация YAML 1.2). Не смешивайте с 4 пробелами в одном файле.
• Кавычки для неоднозначных значений — строки yes, no, 1.0, 2024-01-01 могут быть интерпретированы как булевы, числа или даты. Явно указывайте тип через кавычки при необходимости.
• Валидация схемы — для критичных конфигов (Kubernetes, Docker Compose) используйте валидацию против JSON Schema или встроенные проверки (kubectl apply --dry-run, docker-compose config).
• Версионирование — храните конфиги в Git, используйте осмысленные коммиты. При конвертации между форматами проверяйте, что структура сохранилась.

FAQ

Чем YAML лучше JSON для конфигов?
YAML поддерживает комментарии, читается проще и обычно компактнее. Для конфигов, которые часто правят вручную (Docker, K8s, CI), YAML удобнее. JSON остаётся стандартом для API и машинной обработки.

Можно ли использовать JSON в Docker Compose?
Да. Docker Compose принимает файлы docker-compose.json. Синтаксис описан в документации. На практике чаще используют YAML из-за читаемости.

Как конвертировать большой YAML-файл в JSON?
Используйте онлайн-конвертер для файлов до нескольких мегабайт или скрипт на Python/Node.js с библиотеками PyYAML или js-yaml для очень больших файлов.

Почему YAML чувствителен к отступам?
Структура в YAML задаётся отступами, как в Python. Это уменьшает синтаксический шум, но требует аккуратности: смешение пробелов и табов или неверный уровень вложенности приводит к ошибкам.

Безопасно ли вставлять конфиги с паролями в онлайн-конвертер?
Конвертер reChecker выполняет все операции локально в браузере. Данные не отправляются на сервер и не сохраняются. Тем не менее для конфигов с секретами лучше использовать локальные инструменты (yamllint, скрипты) или убедиться, что в браузере нет расширений, которые могут перехватывать ввод. Для большинства сценариев разовой конвертации встроенная обработка в браузере достаточна.

Заключение

YAML и JSON решают разные задачи: YAML — для человекочитаемых конфигов (Docker, Kubernetes, CI/CD), JSON — для API и обмена данными. Понимание синтаксиса обоих форматов, знание типичных ошибок и умение конвертировать между ними — обязательные навыки для работы с современным стеком. Для быстрой конвертации и валидации используйте онлайн-конвертер YAML ↔ JSON — он работает в браузере, не отправляет данные на сервер и подходит для конфигов любого размера в рамках разумного.