Config и UI schema

Семь обязательных полей

Пример конфигурации

Это учебные ID и пути: настоящие значения выбирайте в форме экземпляра; config-bound manifest менять не нужно. config.example.json не входит в BTP и автоматически не читается менеджером.

{
  "sourceServerId": "demo-source",
  "sourcePath": ["device", "temperature", "value"],
  "destinationServerId": "demo-output",
  "destinationTopic": "BLUETRAKTOR/COMMUNITY/temperature",
  "intervalMs": 5000,
  "scale": 1,
  "offset": 0
}

Подмножество JSON Schema

Корень - object с additionalProperties: false, все семь полей обязательны. Каждому узлу нужен явный type, каждому массиву - items. Вложенные объекты также закрыты. Разрешены только перечисленные ниже keywords; oneOf, $ref и pattern не поддерживаются.

$schema, $id, type, title, description, default, enum,
properties, required, additionalProperties, items,
minimum, maximum, minLength, maxLength, minItems, maxItems

Полная config schema примера

Здесь опущены только человекочитаемые title и description из поставляемой схемы. Структура и ограничения те же; полные файлы входят в загрузку.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["sourceServerId", "sourcePath", "destinationServerId", "destinationTopic", "intervalMs", "scale", "offset"],
  "properties": {
    "sourceServerId": { "type": "string", "minLength": 1, "maxLength": 96 },
    "sourcePath": {
      "type": "array", "minItems": 1, "maxItems": 16,
      "items": { "type": "string", "minLength": 1, "maxLength": 64 }
    },
    "destinationServerId": { "type": "string", "minLength": 1, "maxLength": 96 },
    "destinationTopic": { "type": "string", "minLength": 1, "maxLength": 256 },
    "intervalMs": { "type": "integer", "minimum": 1000, "maximum": 60000, "default": 5000 },
    "scale": { "type": "number", "minimum": -1000, "maximum": 1000, "default": 1 },
    "offset": { "type": "number", "minimum": -1000000, "maximum": 1000000, "default": 0 }
  }
}

UI schema

UI schema выбирает встроенные controls для формы экземпляра. Она не добавляет виджеты панели или системные разделы. serverField указывает соседнее поле с ID сервера; при смене сервера picker очищает старый путь. step задает шаг элемента ввода, а не дополнительное правило валидации.

• Специальные widgets: server-select, usepi-path-select, textarea и slider.
• Boolean, enum, числа, объекты и массивы отображаются общей формой.
• groups объединяет поля в именованные группы, order задает порядок; полный пример есть в архиве.
• Неизвестный widget и неверный serverField отклоняются при inspection.

{
  "groups": [
    { "id": "source", "title": "Источник", "fields": ["sourceServerId", "sourcePath"] },
    { "id": "output", "title": "Результат", "fields": ["destinationServerId", "destinationTopic"] },
    { "id": "processing", "title": "Обработка", "fields": ["scale", "offset", "intervalMs"] }
  ],
  "order": ["sourceServerId", "sourcePath", "destinationServerId", "destinationTopic", "scale", "offset", "intervalMs"],
  "properties": {
    "sourceServerId": { "widget": "server-select" },
    "sourcePath": { "widget": "usepi-path-select", "serverField": "sourceServerId" },
    "destinationServerId": { "widget": "server-select" },
    "destinationTopic": { "placeholder": "BLUETRAKTOR/COMMUNITY/temperature" },
    "intervalMs": { "widget": "slider", "step": 1000 }
  }
}

Проверка предметных условий

Менеджер проверяет schema и сохраненный config; стартер дополнительно проверяет допустимость пути. В сегментах он запрещает пробелы, управляющие символы, /, :, *, +, #, а также . и ... В MQTT-топике запрещены пустые сегменты и начало $. Это сознательно узкий контракт примера. Не переименовывайте реальный путь в config ради обхода ошибки.

Без секретов

Config не является хранилищем секретов. hidden скрывает поле только на экране. Пароли, broker credentials, tokens, cookie, private keys и аналогичные значения сюда не помещаются. Поля password, secret, token, apiKey, privateKey, credential и нормализованные варианты отклоняются; другое имя не делает секрет безопасным. Подключение MQTT настраивает администратор, плагин получает только внутренний server ID и разрешенный topic.

Ограничения размера

Каждая schema ограничена 64 KiB, глубиной 32 и 4096 узлами. Config: 192 KiB, глубина 32, 8192 узла. Это пределы текущего контракта, а не рекомендуемый размер формы. Проверяйте результат inspection на целевой версии менеджера.