marketplaces/docs/platform/02-bootstrap-json-spec.md

02. Спецификация bootstrap.json

Назначение

Bootstrap JSON является главным конфигурационным документом витрины. Он определяет структуру страниц, секций, виджетов, тему и подключение источников данных.

Поведение системы

• Frontend загружает bootstrap.json на старте runtime.
• Конфигурация валидируется по обязательным полям.
• После валидации строится UI без хардкода tenant-логики.

Обязательные свойства

• schemaVersion: string
• tenant: object
• theme: object
• layout: object
• pages: array
• apiEndpoints: object

Обязательные свойства tenant

• id: string
• slug: string
• host: string
• defaultLocale: string
• supportedLocales: string[]

Обязательные свойства страницы

• id: string
• key: string
• route.path: string
• sections: array

Обязательные свойства секции

• id: string
• type: string
• order: number
• widgets: array

Обязательные свойства виджета

• id: string
• type: string
• version: string

Поддерживаемые layout.type

• default
• sidebar-left
• carousel-home
• minimal

Опциональные свойства

• featureFlags
• localization
• seo
• permissions
• branding
• navigation
• footer
• staticPages
• widgetRegistry
• visibility
• layout
• dataSource

Строгие правила

• Поля обязательной схемы не могут быть null.
• route.path должен быть уникальным в рамках tenant.
• id страниц, секций и виджетов должен быть уникальным в своей области.
• В одной секции порядок order не может дублироваться.
• Виджеты не содержат backend URL в props; URL управляются только apiEndpoints.
• Для виджетов допустимы metadata поля: order, padding, visibility.desktop/tablet/mobile.
• Для footer links/legal/payout icons источник истины — bootstrap JSON.
• Для staticPages контент поддерживается в формате multilingual HTML и рендерится только через safe sanitizer.

Пример полного минимального bootstrap

{
  "schemaVersion": "1.0.0",
  "tenant": {
    "id": "tenant-default",
    "slug": "default",
    "host": "default.marketplace.com",
    "defaultLocale": "ru",
    "supportedLocales": ["ru", "en"]
  },
  "theme": {
    "themeId": "default-light",
    "palette": {
      "primary": "#497671",
      "textPrimary": "#1e3c38",
      "backgroundPrimary": "#ffffff"
    }
  },
  "apiEndpoints": {
    "catalog": { "baseUrl": "https://api.marketplace.com" },
    "bootstrap": { "path": "/bootstrap" }
  },
  "pages": [
    {
      "id": "page-home",
      "key": "home",
      "route": { "path": "/", "exact": true },
      "sections": [
        {
          "id": "section-hero",
          "type": "hero",
          "order": 1,
          "widgets": [
            { "id": "widget-hero", "type": "hero", "version": "1.0.0" }
          ]
        }
      ]
    }
  ]
}

Ответственность Frontend

• Валидировать обязательные поля до рендера.
• Применять значения опциональных полей только при наличии.
• Прекращать инициализацию при критической невалидности схемы.

Ответственность Backend

• Отдавать tenant-specific bootstrap.json.
• Поддерживать schemaVersion и changelog контракта.
• Не включать frontend-специфические runtime-хуки в JSON.