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

Схемы документов определяют структуру данных для хранения документов в системе 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. Оставьте возможность для расширения через необязательные поля
Версионирование схем
📋 Стратегия обновлений
  • Всегда тестируйте изменения схемы на тестовых данных
  • Документируйте все изменения в описании схемы
  • Планируйте миграцию данных при несовместимых изменениях
  • Уведомляйте команду разработки об изменениях в схемах
  • Создавайте резервные копии перед принудительными обновлениями
Made on
Tilda