bearingsinfo/data/schemas/README.md

Schema Definitions

Эта директория содержит YAML-схемы для валидации CSV файлов в директории /data/, а также SQL-схему базы данных (bearings_db_schema.sql).

Назначение

Схемы используются для:

• Валидации структуры CSV файлов - проверка наличия обязательных колонок
• Документирования формата данных - описание типов данных в каждой колонке
• Определения уникальных ключей - какие комбинации полей должны быть уникальными
• Порядка сортировки - предпочтительный порядок сортировки записей

Структура схем

Каждая схема представляет собой YAML файл, содержащий JSON-подобную структуру с массивом таблиц:

{
  "tables": [
    {
      "name": "имя_таблицы",           # Логическое имя таблицы
      "path": "data/...",                # Путь к CSV файлу
      "columns": {                       # Определение колонок
        "column_name": "string"          # Имя колонки: тип данных
      },
      "unique": ["col1", "col2"],       # Комбинация полей, которая должна быть уникальной
      "sort_by": ["col1", "col2"]       # Порядок сортировки
    }
  ]
}

Примечание: Схемы хранятся в YAML-файлах, но используют JSON-подобный синтаксис для совместимости с существующими валидаторами.

Доступные схемы

analogs.yaml

Схемы для таблиц аналогов подшипников:

• analogs_gost_iso - соответствия ГОСТ ↔ ISO (data/analogs/gost_iso.csv)
• analogs_units - подшипниковые узлы (data/analogs/units.csv)
• analogs_housings - корпусные подшипники (data/analogs/housings.csv)

Поля:

• source - источник данных (например, "Аналоги/ГОСТ_ISO.md")
• gost - обозначение по ГОСТ
• iso - обозначение по ISO
• brand - производитель (опционально)
• notes - примечания и комментарии

Уникальный ключ: комбинация gost + iso

brands.yaml

Схема для таблицы производителей:

• brands - информация о брендах (data/brands/brands.csv)

Поля:

• brand - название бренда
• country - страна производства
• segment - ценовой/качественный сегмент
• categories - категории продукции
• notes - дополнительная информация
• source - источник данных

Уникальный ключ: brand

gost.yaml

Схемы для данных ГОСТ:

• gost_bearings - подшипники ГОСТ (data/gost/bearings.csv)
• gost_dimensions - габаритные размеры (data/gost/dimensions.csv)
• gost_series - размерные серии (data/gost/series.csv)
• gost_tolerances - допуски и посадки (data/gost/tolerances.csv)

iso.yaml

Схемы для данных ISO:

• iso_bearings - подшипники ISO (data/iso/bearings.csv)
• iso_dimensions - габаритные размеры (data/iso/dimensions.csv)
• iso_prefixes - префиксы обозначений (data/iso/prefixes.csv)
• iso_suffixes - суффиксы обозначений (data/iso/suffixes.csv)

Использование схем

Ручная валидация

Проверить соответствие CSV файла схеме можно с помощью скриптов в /scripts/validate/:

python scripts/validate/validate_csv.py data/analogs/gost_iso.csv schemas/analogs.yaml

Автоматическая валидация

Валидация должна запускаться автоматически:

• При коммите (через git hooks) - планируется
• При запуске тестов (pytest)
• При обновлении данных

Добавление новой схемы

1. Создайте YAML файл в schemas/ с описанием таблицы
2. Укажите путь к CSV, колонки, уникальные ключи и порядок сортировки
3. Добавьте валидацию в скрипты или тесты

Типы данных

Поддерживаемые типы:

• string - текстовая строка
• integer - целое число
• float - число с плавающей точкой
• boolean - логическое значение (true/false)
• date - дата (формат ISO 8601)

Связь с другими директориями

• /data/ - CSV файлы, которые валидируются этими схемами
• /scripts/validate/ - скрипты для валидации CSV по схемам
• /tests/ - тесты, использующие схемы для проверки целостности данных

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

1. Всегда обновляйте схему при изменении структуры CSV файла
2. Документируйте новые поля в комментариях или в этом README
3. Проверяйте уникальность перед добавлением новых записей
4. Соблюдайте порядок сортировки (sort_by) для консистентности данных
5. Используйте одинаковые имена полей во всех связанных таблицах (например, brand везде в единственном числе)

Примечания

• Схемы написаны в формате JSON внутри YAML файлов для совместимости
• Все пути в схемах относительные от корня репозитория
• Уникальные ключи могут быть составными (несколько полей)
• Порядок сортировки важен для читаемости и поиска дубликатов