format-data.md

type: standard
aspect: format
title: "Стандарт форматов данных"
version: 1.0.0
date: 2026-02-19
status: active

Стандарт форматов данных

Правила использования YAML, JSON, CSV, Excel для хранения и обмена данными.

ВЫБОР ФОРМАТА

Матрица применения

Рекомендации по размеру

YAML

Применение

Формат	Когда использовать	Когда НЕ использовать
YAML	Конфиги, метаданные, документация	Большие данные (>10K записей)
JSON	API, логи, небольшие данные	Конфиги (читабельность), большие данные
CSV	Табличные данные, экспорт/импорт	Вложенные структуры, метаданные
Excel	Обмен с бизнесом, отчёты	Автоматизация, версионирование
SQLite	Большие данные (>10K записей), реляционные данные	Конфиги, метаданные

Размер	Формат
< 100 записей	YAML (читабельность)
100 - 1K записей	JSON (скорость парсинга)
1K - 10K записей	CSV (компактность)
10K - 100K записей	SQLite (индексы, запросы)
> 100K записей	PostgreSQL (производительность)

Используем для:
- Конфигурационные файлы (settings.yaml, config.yaml)
- Метаданные документов (frontmatter)
- Схемы данных
- Небольшие справочники (< 100 записей)
- CI/CD конфиги (.gitlab-ci.yml, .github/workflows/)

НЕ используем для:
- Логи (предпочитаем JSON)
- Большие массивы данных (>10K записей)
- API ответы (предпочитаем JSON)

Синтаксис

# Строки
name: "Иван Иванов"
name_unquoted: Иван Иванов  # без кавычек
multiline: |
  Многострочный
  текст

# Числа
age: 30
price: 99.99

# Булевы
active: true
deleted: false

# Null
value: null
empty: ~

# Списки (массивы)
colors:
  - red
  - green
  - blue

# Inline списки
colors: [red, green, blue]

# Словари (объекты)
person:
  name: Ivan
  age: 30
  email: ivan@example.com

# Inline словари
person: {name: Ivan, age: 30}

company:
  name: "ООО Рога и Копыта"
  address:
    city: Moscow
    street: Tverskaya
    building: 1
  employees:
    - name: Ivan
      role: developer
    - name: Maria
      role: designer

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

Правила написания

Отступы:
- Используем 2 пробела (не табы)
- Консистентные отступы на всех уровнях

Кавычки:
- Строки без кавычек если нет спецсимволов
- Двойные кавычки "text" если есть спецсимволы: :, #, -, @
- Не использовать одинарные кавычки

# Комментарий перед блоком
key: value  # Inline комментарий

Именование ключей:
- snake_case для всех ключей
- Без пробелов, без дефисов в ключах (только _)

Валидация

# Проверка синтаксиса
python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"

# Онлайн валидатор
# https://www.yamllint.com/

JSON

Применение

Используем для:
- API запросы/ответы
- Логи (structured logging)
- Данные для обмена между системами
- Небольшие данные (100 - 10K записей)
- Кеширование данных

НЕ используем для:
- Конфиги (предпочитаем YAML для читабельности)
- Большие данные (>10K записей, предпочитаем CSV/SQLite)

Синтаксис

{
  "string": "Текст",
  "number": 42,
  "float": 3.14,
  "boolean": true,
  "null": null
}

{
  "array": [1, 2, 3, 4, 5],
  "object": {
    "name": "Ivan",
    "age": 30
  },
  "nested": {
    "users": [
      {"id": 1, "name": "Ivan"},
      {"id": 2, "name": "Maria"}
    ]
  }
}

Правила написания

Форматирование:
- Отступы: 2 пробела (не табы)
- Кавычки: только двойные " (одинарные ' недопустимы)
- Trailing comma: ЗАПРЕЩЕНА (последняя запятая перед } или ])

Именование ключей:
- snake_case для API внутри платформы
- camelCase если взаимодействуем с внешним API (OZON, 1C)

{
  "user_id": 123,
  "user_name": "Ivan",
  "created_at": "2026-02-19T10:00:00Z"
}

{
  'userId': 123,        // ошибка: одинарные кавычки
  "userName": "Ivan",   // camelCase — только для внешних API
  created_at: "...",    // ошибка: ключ без кавычек
}

Форматирование

# Python
python3 -m json.tool input.json > output.json

# jq
jq '.' input.json > output.json

# jq
jq -c '.' input.json

Валидация

# Python
python3 -c "import json; json.load(open('file.json'))"

# jq
jq empty file.json

# Онлайн валидатор
# https://jsonlint.com/

CSV

Применение

Используем для:
- Экспорт/импорт табличных данных
- Обмен данными с Excel/Google Sheets
- Большие плоские данные (1K - 100K записей)
- Логи (альтернатива JSON)

НЕ используем для:
- Вложенные структуры (используем JSON/YAML)
- Метаданные (используем YAML frontmatter)
- API (используем JSON)

Синтаксис

id,name,age,city
1,Ivan,30,Moscow
2,Maria,25,Saint Petersburg
3,Peter,35,Kazan

id,name,description
1,Product A,"High quality, durable"
2,Product B,"Multi-line
description"

Правила написания

Заголовок:
- Первая строка — обязательно заголовки столбцов
- Заголовки в snake_case

Разделитель:
- Запятая , (не точка с запятой ;)
- Исключение: экспорт для Excel РФ (использует ; и кодировку Windows-1251)

Кавычки:
- Двойные " если значение содержит:
- Запятую ,
- Перенос строки \n
- Двойную кавычку " (экранируется удвоением "")

Кодировка:
- UTF-8 (по умолчанию для всех CSV)
- UTF-8 with BOM для Excel (если нужна совместимость)
- Windows-1251 только для старых версий Excel РФ

Пустые значения:
- Пустая строка "" для пустого текста
- Пропуск поля ,, для NULL (если формат поддерживает)

Примеры

product_id,name,price,stock
1,Товар А,100.50,15
2,Товар Б,200.00,0
3,Товар В,150.75,5

product_id,name,description,tags
1,"Товар А","Описание с запятой, и точкой","tag1,tag2"
2,"Товар ""Специальный""","С кавычками","tag3"

Чтение/Запись

import csv

# Чтение
with open('data.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(row['name'], row['price'])

# Запись
with open('output.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=['id', 'name', 'price'])
    writer.writeheader()
    writer.writerow({'id': 1, 'name': 'Product', 'price': 100})

# Пропустить заголовок, показать 2-й столбец
tail -n +2 data.csv | cut -d',' -f2

Excel (XLSX)

Применение

Используем для:
- Обмен данными с бизнесом (отправка отчётов)
- Сложные таблицы (форматирование, формулы)
- Импорт данных от поставщиков/клиентов

НЕ используем для:
- Хранение данных (используем CSV/SQLite)
- Версионирование (бинарный формат, не git-friendly)
- Автоматизация (используем CSV/JSON)

Правила работы

import pandas as pd

# Чтение первого листа
df = pd.read_excel('data.xlsx', sheet_name=0)

# Чтение конкретного листа
df = pd.read_excel('data.xlsx', sheet_name='Products')

# Чтение всех листов
all_sheets = pd.read_excel('data.xlsx', sheet_name=None)

import pandas as pd

df = pd.DataFrame({
    'id': [1, 2, 3],
    'name': ['A', 'B', 'C'],
    'price': [100, 200, 300]
})

# Запись
df.to_excel('output.xlsx', index=False, sheet_name='Products')

# Несколько листов
with pd.ExcelWriter('output.xlsx') as writer:
    df1.to_excel(writer, sheet_name='Products', index=False)
    df2.to_excel(writer, sheet_name='Orders', index=False)

import pandas as pd

# Читать Excel
df = pd.read_excel('input.xlsx')

# Сохранить как CSV
df.to_csv('output.csv', index=False, encoding='utf-8')

КОНВЕРТАЦИЯ МЕЖДУ ФОРМАТАМИ

YAML ↔ JSON

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)

import yaml
import json

with open('data.json') as f:
    data = json.load(f)

with open('data.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False, allow_unicode=True)

CSV ↔ JSON

import csv
import json

with open('data.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    data = list(reader)

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

import csv
import json

with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# data должен быть список словарей
with open('data.csv', 'w', encoding='utf-8', newline='') as f:
    if data:
        writer = csv.DictWriter(f, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)

Excel ↔ CSV

# Использовать Python pandas (см. выше)
python3 -c "import pandas as pd; pd.read_excel('data.xlsx').to_csv('data.csv', index=False)"

python3 -c "import pandas as pd; pd.read_csv('data.csv').to_excel('data.xlsx', index=False)"

СПЕЦИАЛЬНЫЕ СЛУЧАИ

Даты и время

# YAML
created_at: 2026-02-19T10:30:00Z          # UTC
updated_at: 2026-02-19T13:30:00+03:00     # Moscow time

{
  "created_at": "2026-02-19T10:30:00Z",
  "updated_at": "2026-02-19T13:30:00+03:00"
}

Правила:
- Всегда указывать timezone (Z для UTC или +03:00)
- Формат: YYYY-MM-DDTHH:MM:SSZ
- НЕ использовать: 19.02.2026, 19/02/26, Unix timestamp

Большие числа

JSON:
- Числа > 2^53 (JavaScript limit) хранить как строки
- ID > 1 триллиона → строка

{
  "order_id": "1234567890123456789",  // строка!
  "price": 100.50                      // число
}

Многострочные строки

# Literal block (сохраняет переносы)
description: |
  Строка 1
  Строка 2
  Строка 3

# Folded block (заменяет переносы на пробелы)
description: >
  Длинный текст
  который будет
  в одной строке

{
  "description": "Строка 1\nСтрока 2\nСтрока 3"
}

ИНСТРУМЕНТЫ

Валидация и форматирование

Редакторы

Формат	Инструмент	Команда
YAML	yamllint	`yamllint file.yaml`
YAML	Python	`python3 -c "import yaml; yaml.safe_load(open('f.yaml'))"`
JSON	jq	`jq empty file.json`
JSON	Python	`python3 -m json.tool file.json`
CSV	csvlint	`csvlint file.csv`

VSCode расширения:
- YAML: redhat.vscode-yaml
- JSON: встроенный
- CSV: mechatroner.rainbow-csv

CHANGELOG

2026-02-19 — v1.0.0

Версия: 1.0.0
Статус: active
Владелец: architect