Схемы JSON

Portable Docara использует JSON Schema Draft 2020-12 и fail closed отклоняет unknown fields, неверные типы и unsafe paths.

Исполняемые примеры schema

Valid minimal site:

{
  "schema": "docara.site.v1",
  "preset": "docs",
  "framework_lock": "simai-framework.lock.json"
}

Invalid site с unknown field:

{
  "schema": "docara.site.v1",
  "preset": "docs",
  "framework_lock": "simai-framework.lock.json",
  "unknown_setting": true
}

Invalid-пример документирует ожидаемую ошибку; не копируйте его в проект.

Scope

schema обязателен. Optional version, если присутствует, равен 1 и обозначает версию schema, а не версию документации.

Presentation branches

• branding: непустые title/label, mode (full, compact, logo, text), size (small, medium, large) и относительные пути brand assets;
• layout.key: registered value docara.docs;
• layout.container.max: integer 1..8, mapped to SIMAI Framework max-container-1..8;
• layout.regions.<name>.enabled: boolean;
• layout.regions.<name>.sections: ordered registered Section -> Block -> Smart calls;
• settings.theme: system, light, dark;
• settings.modal_blur: none, small, medium, large;
• settings.ui_radius: default, medium, large;
• reader_preferences.enabled: boolean;
• reader_preferences.view: side-panel;
• reader_preferences.hidden_fields: необязательный список встроенных полей, которые не нужно показывать;
• reader_preferences.groups: непустой список зарегистрированных групп и полей; runtime дополнительно проверяет неизвестные ID, повторы, принадлежность группе и безопасный effect contract;
• navigation.hidden: boolean;
• navigation.order: integer 0..2147483647;
• search.enabled, search.indexed: boolean;
• reading.breadcrumbs, reading.toc, reading.previous_next: boolean;
• reading.mobile_toc: auto, always, never;
• reading.toc_depth: integer 2..6.

Branch должен содержать хотя бы одно поле. {} и [] отклоняются. Явная очистка записывается как {"$reset": true}; reset можно совместить с новыми ключами этой же ветки.

Defaults

Resolver устанавливает:

{
  "content_root": "content",
  "layout": {
    "key": "docara.docs",
    "regions": {
      "header": { "enabled": true },
      "sidebar": { "enabled": true },
      "main": { "enabled": true },
      "outline": { "enabled": true },
      "footer": { "enabled": false }
    }
  },
  "search": {
    "enabled": false,
    "indexed": true
  },
  "reading": {
    "breadcrumbs": true,
    "toc": true,
    "mobile_toc": "auto",
    "toc_depth": 3,
    "previous_next": true
  }
}

Структурные defaults областей восстанавливаются после branch reset. main является обязательной областью и не может быть выключен. Допустимые section/block/Smart IDs и фиксированные data bindings дополнительно проверяются runtime resolver.

Значения starter, например включённый search UI, приходят из поставляемого docara.json, а не из скрытого default.

Effective component catalog

Machine-readable catalog объединяет native Markdown, typed Docara и Smart-компоненты, допущенные exact Framework lock. Requirement records фиксируют недоступные потребности, но не callable syntax.

Root содержит immutable framework/provider identity, sorted entries, content_sha256 и bounded nonclaims. Exact параметры, states, limitations и examples принадлежат source records/fixtures и показываются в справочнике компонентов, а не повторяются здесь.

_docara/component-catalog.json является output. Автор не редактирует его и не может через него, Markdown или presentation JSON расширить Smart surface.

Runtime checks beyond schema

Schema подтверждает форму, но builder дополнительно проверяет:

• существование и confinement paths;
• symlink и reserved destinations;
• brand asset type/size/hash;
• Framework lock semantics и immutable references;
• manifest, props, dependencies и asset projection;
• принадлежность каждой страницы объявленному locale, BCP 47 tags, непересекающиеся content roots, fallback-циклы, locales.missing_page_policy и отдельную documentation_version;
• redirect target existence, collision, chain/cycle и confinement внутри base_url;
• output collisions.

Поэтому schema-valid JSON ещё не гарантирует успешную сборку, если внешний файл или runtime contract нарушен.