Документация

Схема документа

Схемы документов определяют структуру данных для хранения документов в системе SOBERIS. Конструктор схем предоставляет визуальный интерфейс для создания и редактирования JSON Schema.

Доступ к конструктору схем документов

Конструктор схем документов доступен по адресу /create/document-scheme для создания новых схем или /update/document-scheme/:versionId для редактирования существующих.

🔗 Навигация к конструктору

Со страницы схем: кнопка "Создать схему документа"
Из редактирования: кнопка "Редактировать" для выбранной схемы
Прямой доступ по URL с указанием versionId для редактирования

Интерфейс конструктора

Заголовок и панель инструментов

В верхней части конструктора расположены основные элементы управления:

Поле описания схемы

Под панелью инструментов расположено текстовое поле для ввода описания схемы. Описание помогает понять назначение схемы и отображается в метаданных JSON Schema.

Основная рабочая область

Интерфейс разделен на две основные части:

Конструктор схемы (левая панель)

Древовидное представление структуры схемы
Поля ввода названий свойств
Выпадающие списки типов данных
Кнопки добавления и удаления свойств
Индикаторы обязательных полей

Панель деталей (правая панель)

Детальные настройки выбранного свойства
Ограничения и валидация
Описание и примеры
Настройки индексации
Предварительный просмотр схемы

Типы данных

Базовые типы

Конструктор поддерживает следующие базовые типы данных JSON Schema:

Специальные типы (Foreign Keys)

SOBERIS поддерживает специальные типы для связей между документами и каталогами:

# Document FK
# Ссылка на документ в другой коллекции. Требует указания коллекции документов.

{
  "type": "string",
  "x-document-collection": "users"
}

# Directory FK
# Ссылка на элемент каталога. Требует указания коллекции каталога и параметра.

{
  "type": "string",
  "x-directory-collection": "departments",
  "x-directory-param": "name"
}

Форматы строк

Для строкового типа доступны стандартные форматы JSON Schema:

date - Дата (YYYY-MM-DD)
date-time - Дата и время
time - Время
email - Email адрес
hostname - Имя хоста
ipv4 - IPv4 адрес
ipv6 - IPv6 адрес
uri - URI
uuid - UUID

Работа с конструктором

Создание базовой структуры

1. Задайте название схемы в корневом элементе
2. Добавьте описание схемы в текстовом поле
3. Нажмите "+" для добавления нового свойства
4. Выберите тип данных из выпадающего списка
5. Настройте детали в правой панели

Добавление свойств

Новые свойства добавляются через кнопку "+" рядом с родительским элементом:

На корневом уровне - создает свойство схемы верхнего уровня
В объекте - добавляет вложенное свойство объекта
В массиве - определяет тип элементов массива

⚠️ Ограничения на именование

Только латинские символы (a-z, A-Z, 0-9, _)
Имена должны быть уникальными в рамках родительского объекта
Нельзя использовать зарезервированные слова: "items"
Имя не может быть пустым

Настройка ограничений

В правой панели можно настроить детальные ограничения для каждого типа:

Индексация полей

Для полей схемы документа можно настроить индексы MongoDB:

Single Field

Обычный индекс по одному полю для быстрого поиска и сортировки.

Text

Текстовый индекс для полнотекстового поиска по содержимому поля.

Multikey

Индекс для массивов, позволяющий индексировать каждый элемент массива.

Валидация и ограничения

Проверки при сохранении

Перед сохранением схемы система выполняет комплексную валидацию:

🚫 Блокирующие ошибки

Пустые имена - все свойства должны иметь непустые имена
Дублирующиеся имена - имена свойств в одном объекте должны быть уникальными
Некорректные символы - только латинские символы в именах
Незаполненные FK поля - коллекции и параметры для Foreign Key должны быть указаны
Дублирующееся имя схемы - при создании имя схемы должно быть уникальным

Проверка совместимости

При обновлении существующей схемы система проверяет обратную совместимость:

Разрешенные изменения:

Добавление новых необязательных полей
Изменение обязательного поля на необязательное
Добавление значений в enum
Расширение ограничений (увеличение maxLength, уменьшение minLength)

Запрещенные изменения:

Удаление существующих полей
Изменение типа существующего поля
Изменение необязательного поля на обязательное
Удаление значений из enum
Ужесточение ограничений

Принудительное обновление

При нарушении совместимости система предложит принудительное обновление с предупреждением о последствиях:

⚠️ Последствия принудительного обновления

Возможны ошибки валидации существующих документов
Требуется проверка и обновление связанных систем
Может потребоваться миграция данных
Создается новая версия схемы с несовместимыми изменениями

Примеры схем

Простая схема пользователя

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "User",
  "description": "Схема данных пользователя",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Уникальный идентификатор",
      "x-index": "single_field"
    },
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 50,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "Имя пользователя",
      "x-index": "single_field"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email адрес",
      "x-index": "single_field"
    },
    "active": {
      "type": "boolean",
      "description": "Активность пользователя"
    }
  },
  "required": ["id", "username", "email"],
  "additionalProperties": false
}

Схема с вложенными объектами

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Order",
  "description": "Схема заказа",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "x-index": "single_field"
    },
    "customerId": {
      "type": "string",
      "x-document-collection": "customers",
      "x-index": "single_field"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "x-document-collection": "products"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "price": {
            "type": "number",
            "minimum": 0
          }
        },
        "required": ["productId", "quantity", "price"],
        "additionalProperties": false
      },
      "minItems": 1
    },
    "status": {
      "type": "string",
      "enum": ["pending", "processing", "shipped", "delivered", "cancelled"],
      "x-index": "single_field"
    }
  },
  "required": ["id", "customerId", "items", "status"],
  "additionalProperties": false
}

Схема с Foreign Key связями

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Employee",
  "description": "Схема сотрудника",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "x-index": "single_field"
    },
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "lastName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "departmentId": {
      "type": "string",
      "x-directory-collection": "departments",
      "x-directory-param": "id",
      "description": "Ссылка на отдел",
      "x-index": "single_field"
    },
    "managerId": {
      "type": "string",
      "x-document-collection": "employees",
      "description": "Ссылка на руководителя",
      "x-index": "single_field"
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "string",
        "x-directory-collection": "skills",
        "x-directory-param": "name"
      },
      "uniqueItems": true
    }
  },
  "required": ["id", "firstName", "lastName", "departmentId"],
  "additionalProperties": false
}

Работа с файлами

Импорт схемы

Конструктор поддерживает импорт готовых JSON Schema из файлов:

1. Нажмите кнопку "Импорт" в панели инструментов
2. Выберите JSON файл с валидной JSON Schema
3. Система проверит схему на корректность
4. При успешной проверке схема загрузится в конструктор
5. Все SOBERIS-специфичные расширения будут интерпретированы

Экспорт схемы

Созданную схему можно сохранить локально для резервного копирования или передачи:

1. Нажмите кнопку "Скачать схему"
2. Браузер сохранит файл с именем "НазваниеСхемы.json"
3. Файл содержит полную JSON Schema со всеми настройками
4. Включены все SOBERIS расширения (x-index, x-document-collection и т.д.)

Расширения SOBERIS

Индексы MongoDB

SOBERIS использует расширение x-index для автоматического создания индексов:

Foreign Key расширения

Для реализации связей между коллекциями используются специальные расширения:

Обработка ошибок

Ошибки валидации

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

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

Пустое имя свойства - все свойства должны иметь имя
Дублирующееся имя - имена в одном объекте должны быть уникальными
Некорректные символы - только латинские символы в именах
Незаполненная коллекция FK - для Foreign Key обязательно указывать коллекцию
Существующее имя схемы - при создании имя должно быть уникальным

Ошибки совместимости

При нарушении обратной совместимости система предупреждает о проблемах и предлагает решения:

# Пример сообщения об ошибке совместимости:

# Обнаружены несовместимые изменения:
• Изменен тип поля 'age' с 'string' на 'integer'
• Удалено обязательное поле 'email'
• Добавлено обязательное поле 'newField'

# Эти изменения могут нарушить работу с существующими данными.
Продолжить с принудительным обновлением?

Лицензионные ограничения

Некоторые функции требуют наличия действующей лицензии:

🔐 Лицензированные функции

Расширенные типы данных в конфигурациях
Принудительное обновление схем
Специальные расширения схем

Настройки конфигурации

Переменные окружения

Поведение конструктора настраивается через переменные окружения:

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

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

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

Используйте camelCase для имен полей: firstName, createdAt
Используйте PascalCase для имен схем: UserProfile, OrderItem
Добавляйте описания ко всем полям для понимания назначения
Используйте семантически понятные имена: userId вместо uid
Группируйте связанные поля в объекты: address.street, address.city

Планирование структуры

1. Проанализируйте структуру данных перед созданием схемы
2. Определите обязательные поля на основе бизнес-логики
3. Спланируйте индексы для часто используемых полей поиска
4. Продумайте связи с другими коллекциями через Foreign Keys
5. Оставьте возможность для расширения через необязательные поля

Версионирование схем

📋 Стратегия обновлений

Всегда тестируйте изменения схемы на тестовых данных
Документируйте все изменения в описании схемы
Планируйте миграцию данных при несовместимых изменениях
Уведомляйте команду разработки об изменениях в схемах
Создавайте резервные копии перед принудительными обновлениями