Схема Aggrega Catalog (Feature)
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Модульная эксплуатационная функция, которая динамически привязывается к компонентам.
Описательное руководство по созданию сущностей Feature см. в справочнике по созданию сущностей Feature; на этой странице документирована структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “Feature” | да | Константа: "Feature" |
metadata | object | да | |
spec | object | да | Контракт валидации, нацеливания и совместимости для сущности Feature из каталога: столпы свободной формы (values, infra, provides), задаваемые через schema, столпы фиксированной формы (usesSchema — гнёзда зависимостей, featuresSchema — слоты подключения), нацеливание на компоненты (appliesTo и appliesToAnyOf) и средства управления совместимостью. |
Дополнительные свойства не допускаются.
feature.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
version | string | да | Версия feature по строгому семантическому версионированию (например, 1.0.0). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | нет | Что представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что нужно читателю, чтобы выбрать её и правильно использовать: чего она ожидает от сущности Release, которая её развёртывает, и всё неожиданное в её поведении. Обычно достаточно короткого абзаца. |
maintainers | object[] | нет | Список сопровождающих, которым принадлежит эта сущность. |
license | string | нет | Идентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла. |
repository | string | нет | URL Git-репозитория, в котором находятся исходные файлы. |
home | string | нет | URL домашней страницы, вики или документации этой сущности. |
keywords | string[] | нет | Список описательных ключевых слов для удобства поиска в интерфейсе. |
labels | object | нет | Метки для утиной типизации сущности Feature. Зарезервированная метка ‘feature.aggrega.ai/kind’ со значением ‘secret’ помечает её как Feature учётных данных — для автора и для инструментов, которые её отображают. Feature учётных данных и обычная Feature подключаются одинаково, через одну и ту же поверхность подключения; то, что порождает подключение, определяется не меткой, а сущностью FeatureRecipe, с которой Manifest сопоставляет её тип. |
annotations | map of string | нет | Неизменяемые внутренние характеристики функции, задаваемые архитектором платформы в домене 2. Каскадно передаются в корзину .context.annotations.catalog. |
Дополнительные свойства не допускаются.
feature.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
feature.metadata.labels
Метки для утиной типизации сущности Feature. Зарезервированная метка ‘feature.aggrega.ai/kind’ со значением ‘secret’ помечает её как Feature учётных данных — для автора и для инструментов, которые её отображают. Feature учётных данных и обычная Feature подключаются одинаково, через одну и ту же поверхность подключения; то, что порождает подключение, определяется не меткой, а сущностью FeatureRecipe, с которой Manifest сопоставляет её тип.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | нет | Метка вида функции. Значение ‘secret’ помечает её как Feature учётных данных. Допустимые значения: "secret" |
feature.spec
Контракт валидации, нацеливания и совместимости для сущности Feature из каталога: столпы свободной формы (values, infra, provides), задаваемые через schema, столпы фиксированной формы (usesSchema — гнёзда зависимостей, featuresSchema — слоты подключения), нацеливание на компоненты (appliesTo и appliesToAnyOf) и средства управления совместимостью.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
extends | string | нет | Ссылка на базовую сущность Feature, от которой наследует эта сущность Feature. Базовая сущность указывается по её metadata.name, а не по координате реестра, под которой публикуется Feature, и принимает те же три формы версии, что и любая ссылка каталога: без версии (core/queue) — наивысший доступный релиз, точная версия (core/queue:1.0.0) или диапазон с кареткой (core/queue:^1.0.0). Наследуются не только метаданные: metadata.labels и metadata.annotations базовой сущности, её селекторы appliesTo и appliesToAnyOf, её блок interoperability, её usesSchema и её featuresSchema объединяются вниз по иерархии, а её объявления JSON Schema 2020-12 в schema объединяются автоматически. При совпадении ключа побеждает собственное значение потомка, а поля идентичности никогда не наследуются. |
featuresSchema | map of object | нет | Декларативные определения слотов присоединения: именованные точки привязки, в которых эта сущность Feature ожидает присоединения ещё одной сущности Feature. Слот ограничивает, какое заполнение может к нему привязаться (selector) и как может доставляться материал заполнения (inject); контракт values и infra принадлежит собственной сущности Feature заполнения. Объявление слота никогда не закрывает блок присоединений — автор может присоединить Feature под именем, которое не объявлено ни одним слотом. Слот — это точка привязки, а не гнездо зависимости: usesSchema объявляет отдельную поверхность топологии. |
appliesTo | string | нет | Строка селектора меток в стиле Kubernetes, сопоставляемая с Components. Все требования, разделённые запятыми, должны выполняться (AND). Поддерживаемые формы: key=value, key!=value, key in (v1, v2), key notin (v1, v2), голый ключ (метка присутствует), !key (метка отсутствует). Пример: “tier in (critical, production), !legacy”. Пустой или отсутствующий селектор не объявляет ограничений. Селектор разбирается по этим формам при каждой оценке присоединения этой сущности Feature, и требование вне их останавливает сборку с указанием этого требования: пустое требование (ведущая, завершающая или двойная запятая) или ключ, содержащий пробельные символы или любой из символов = ! ( ) и запятую, — поэтому “!tier=frontend” отклоняется, а исключить значение можно с помощью tier!=frontend. Значение — это текст после оператора, какие бы символы он ни содержал. Шаблон этого поля отклоняет лишь несколько некорректных форм, до оценки какого-либо присоединения. Шаблон: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string или map из string[] | нет | Список селекторов; сущность Feature применяется, если совпадает ЛЮБОЙ элемент (логика OR). Каждый элемент — либо строка селектора меток (та же грамматика, что у appliesTo; требования внутри строки объединяются через AND), либо плоская карта ключ-значение, в которой должна совпадать каждая пара (только равенство). |
interoperability | object | нет | Расширенные средства управления эксплуатационной безопасностью и совместимостью. |
usesSchema | map of object | нет | Сокеты зависимостей, которые объявляет эта сущность, с именем сокета в качестве ключа; каждое соединение, проведённое через сокет, проверяется на соответствие объявлению этого сокета — его селектору и допустимым механизмам inject. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
schema | object | нет | Содержимое JSON Schema 2020-12, охватывающее свободные опоры: values (область разработчика — параметры формы приложения, которые разработчик настраивает для каждого подключения Feature в Aggregate); infra (область оператора — физические параметры масштабирования, задаваемые Release); и provides (ключи контекста для нижестоящих потребителей, которые этот Feature предоставляет через канал топологии). Поддерживаются три режима описания с выбором по форме содержимого: (1) встроенное содержимое (YAML-словарь в компактной форме, в виде JSON Schema YAML или смешанный); (2) замена файлом через {$import: |
assertions | map of string | нет | Межполевая валидация во время сборки. Каждая запись — именованное утверждение: ключ — стабильный идентификатор правила, выводимый в сообщениях об ошибках; значение — строка шаблона Go с семантикой остановки {{ fail "message" }}. Несколько именованных утверждений одной сущности оцениваются для каждого экземпляра в порядке, объявленном автором; первое невыполненное утверждение останавливает сборку. Утверждения Feature оцениваются после разрешения и статического анализа, до рендеринга, и выражают архитектурные инварианты контракта. Контекст шаблона: .values / .infra / .uses / .features / .metadata. Вычислитель использует missingkey=error: ссылки на неопределённые ключи останавливают сборку с диагностикой об отсутствующем ключе. Поскольку голая ссылка останавливает сборку до того, как сработает какой-либо запасной вариант, простой default не даёт запасного значения для необязательного поля на этой поверхности — защитите ссылку с помощью hasKey или используйте вспомогательную функцию optional, которая сама выполняет проверку наличия. Чтение ключа через index тоже его не даёт: index останавливает сборку на ключе, которого нет в карте, с указанием этого ключа. |
Дополнительные свойства не допускаются.
feature.spec.interoperability
Расширенные средства управления эксплуатационной безопасностью и совместимостью.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
conflictsWith | string[] | нет | Имена сущностей Features, вместе с которыми эта сущность Feature не может оказаться на одном компоненте; каждое записывается так, как тип присоединения именует Feature. Сборка останавливается до рендеринга, если на одном компоненте оказываются эта сущность Feature и названная здесь Feature, — независимо от того, была ли каждая присоединена на компоненте, на содержащей его подсистеме или границе, в записи компонента Release или путём расширения по аннотациям. Достаточно одного объявления: для остановки не требуется, чтобы другая Feature указывала эту. Имена сравниваются без версии, поэтому запись совпадает с любой версией названной ею Feature. Две сущности Features, присоединённые к соседним границам без общих компонентов, никогда не встречаются и не вызывают остановки. |
Дополнительные свойства не допускаются.