Схема Aggrega Developer Intent (Aggregate)
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
Рекурсивная параметризованная архитектура ИИ. Выступает одновременно как корень сборки и как переиспользуемый модуль.
Описание того, как создавать сущности Aggregate, см. в справочнике по созданию сущностей Aggregate; на этой странице документирована структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | да | Константа: "Aggregate" |
metadata | object | да | |
defs | string[] | нет | Необязательный блок для стандартных якорей YAML (& и *), позволяющий избегать повторов в сущности Aggregate (DRY) и при этом сохранять для компилятора плоский словарь с доступом за O(1). Повторяет аналогичный блок в сущности Manifest. |
spec | object | да | Поверхность намерений разработчика (Developer Intent): глобальный контракт параметров, импорты вложенных агрегатов, публичный API экспортируемых компонентов, группировки по подсистемам и экземпляры компонентов, из которых состоит модуль. |
Дополнительные свойства не допускаются.
aggregate.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
version | string | да | Версия модуля aggregate по строгому семантическому версионированию. Шаблон: ^(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 | нет | |
maintainers | object[] | нет | Список сопровождающих, которым принадлежит эта сущность. |
license | string | нет | Идентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла. |
repository | string | нет | URL Git-репозитория, в котором находятся исходные файлы. |
home | string | нет | URL домашней страницы, вики или документации этой сущности. |
keywords | string[] | нет | Список описательных ключевых слов для удобства поиска в интерфейсе. |
labels | map of string | нет | Метки уровня модуля в духе утиной типизации для поиска в каталоге, оценки политик и фильтрации в Studio/IDE. Эти метки описывают идентичность сущности Aggregate как переиспользуемого модуля (например, aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). Они НЕ распространяются на дочерние узлы компонентов — метки компонентов берутся исключительно из сущности каталога Component в домене 2. |
Дополнительные свойства не допускаются.
aggregate.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
aggregate.spec
Поверхность намерений разработчика (Developer Intent): глобальный контракт параметров, импорты вложенных агрегатов, публичный API экспортируемых компонентов, группировки по подсистемам и экземпляры компонентов, из которых состоит модуль.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
parameters | map of object | нет | Глобальный контракт окружения. Каждая запись — объект типизированного контракта, использующий подмножество словаря компактной формы (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). Вложенная структура выражается через подполе properties: типизированной формы. Значения для сущности Release можно задать встроенно (parameters: {…}) или импортом из одного файла (parameters: {$import: |
aggregates | map of object | нет | Вложенные агрегаты, выступающие в роли импортируемых модулей. Ключи: одна или несколько букв, цифр, символов подчёркивания или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
exportedComponents | map of string | нет | Публичный интерфейс API. Сопоставляет открытое публичное имя с внутренним ID компонента. Родительские сущности Aggregates, импортирующие этот модуль, ссылаются на компоненты по этим публичным именам. |
subsystems | map of subsystem | нет | Именованные логические группировки компонентов сущности Aggregate в подсистемы. Взаимоисключающе с components верхнего уровня — объявление обоих отклоняется. Подсистема, которую автор называет default, — обычная объявленная подсистема, отличная от синтезированной подсистемы default, которую компилятор создаёт для сущности Aggregate, содержащей только components. Ключи: одна или несколько букв, цифр, символов подчёркивания или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
components | map of component_instance | нет | Карта логических атомарных компонентов, из которых состоит эта сущность Aggregate, заданных непосредственно на верхнем уровне. components верхнего уровня и subsystems взаимоисключающи — объявление обоих отклоняется. Если компоненты заданы здесь (без subsystems), компилятор при загрузке помещает их в синтезированную подсистему default, а IR помечает эту подсистему как синтезированную. Ключи: одна или несколько букв, цифр, символов подчёркивания или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.
Определения
inject_delivery
Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или собственный ключ, специфичный для механизма) и ровно одно из полей: ‘from’ (ключ provides для разрешения) или ‘value’ (литеральная строка, которая может содержать выражения шаблонов Go, вычисляемые при разрешении self-inject). ‘from’ разрешается по provides цели в контексте uses[].inject, по provides, которые публикует сущность FeatureRecipe подключения, в контексте features.
Тип: object[]
inject_block
Агностичная маршрутизация внедрения. Сопоставляет локальные переменные ключам provides цели (uses[].inject), ключам provides, которые публикует сущность FeatureRecipe подключения (features.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
env | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или собственный ключ, специфичный для механизма) и ровно одно из полей: ‘from’ (ключ provides для разрешения) или ‘value’ (литеральная строка, которая может содержать выражения шаблонов Go, вычисляемые при разрешении self-inject). ‘from’ разрешается по provides цели в контексте uses[].inject, по provides, которые публикует сущность FeatureRecipe подключения, в контексте features. |
file | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или собственный ключ, специфичный для механизма) и ровно одно из полей: ‘from’ (ключ provides для разрешения) или ‘value’ (литеральная строка, которая может содержать выражения шаблонов Go, вычисляемые при разрешении self-inject). ‘from’ разрешается по provides цели в контексте uses[].inject, по provides, которые публикует сущность FeatureRecipe подключения, в контексте features. |
arg | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или собственный ключ, специфичный для механизма) и ровно одно из полей: ‘from’ (ключ provides для разрешения) или ‘value’ (литеральная строка, которая может содержать выражения шаблонов Go, вычисляемые при разрешении self-inject). ‘from’ разрешается по provides цели в контексте uses[].inject, по provides, которые публикует сущность FeatureRecipe подключения, в контексте features. |
component_uses_block
Соединения, которые компонент проводит к компонентам, от которых он зависит, с ключами по сокетам. Каждый сокет перечисляет свои цели или называет каждое соединение под псевдонимом. Соединение, названное под псевдонимом, может содержать значения разработчика для этого соединения и вложения, заполняющие слоты, объявленные сокетом.
Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
Значения: string[] or map of object.
Другие ключи не допускаются.
feature_uses_block
Соединения, которые проводит присоединённая сущность Feature, с ключами по сокету, который Feature объявляет в своей usesSchema. Каждый сокет перечисляет свои цели или называет каждое соединение под псевдонимом. Соединение, проводимое сущностью Feature, не содержит собственных вложений: нужные ему учётные данные заполняют слот, который Feature объявляет в собственной featuresSchema, и присоединяются рядом с Feature.
Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
Значения: string[] or map of object.
Другие ключи не допускаются.
connection_attachment
Одно вложение, которое содержит соединение: сущность Feature, заполняющая слот, объявленный сокетом соединения, вместе с конфигурацией разработчика для неё.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | да | URI интерфейса Feature, который запрашивает это вложение (например, core/referenced-secret:1.0.0). |
description | string | нет | Необязательная документация, объясняющая, почему соединение содержит это вложение. |
values | object | нет | Конфигурация для Feature, предоставляемая разработчиком и проверяемая по объявлению её схемы. |
Дополнительные свойства не допускаются.
subsystem
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
description | string | нет | Необязательная документация, описывающая назначение этой подсистемы и логическую группировку, которую она представляет. |
annotations | map из string, object или null | нет | Аннотации разработчика для этой подсистемы. Значения — строки, структурированные объекты (карта подключей и значений, сливаемая по каждому подключу с унаследованным структурированным значением) или null; явный null для ключа, унаследованного от родительской подсистемы, удаляет унаследованную привязку из этой подсистемы (отказ от Feature через аннотации). Объявленные здесь аннотации наследуются вложенными подсистемами и содержащимися компонентами; для каждого ключа побеждает более близкий уровень. Каскадно передаются в корзину .context.annotations.aggregate каждого производного узла IR. |
features | map of object | нет | Сквозные features, присоединяемые ко всем компонентам этой подсистемы. Та же схема, что и у features уровня компонента (type, values, uses, inject). При финализации графа разворачиваются в каждый компонент и располагаются в порядке выполнения после features уровня компонента. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
subsystems | map of subsystem | нет | Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
components | map of component_instance | нет | Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.
component_instance
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | да | Запрашиваемая абстрактная сущность Component в виде ссылки: её metadata.name и необязательная :version (например, core/api-server:1.0.0), но никогда не путь к файлу. Разрешается по трёхуровневой модели разрешения сущностей (каталоги каталога рабочего пространства → кэш → реестр): локально созданная сущность Component размещается в catalog/ в корне рабочего пространства или в каталоге, указанном в workspace.catalog_dirs, а type, записанный как относительный путь к файлу, останавливает сборку как сущность, которой нет ни в одном каталоге. |
active | boolean или string | нет | Присутствует ли этот компонент в скомпилированной топологии. Логическое значение или строковый шаблон над .parameters, который должен разрешаться в логическое значение. Если он разрешается в false, компонент удаляется из топологии вместе с его рёбрами uses и его вложениями. Если задавать значение через параметр, сущность Release может включать и выключать присутствие компонента, заполняя этот параметр. Если не указано, по умолчанию true. По умолчанию: true |
description | string | нет | Необязательная документация, описывающая роль этого экземпляра компонента в приложении. Переносится в граф IR. |
annotations | map из string, object или null | нет | Аннотации к этому компоненту, заданные разработчиком. Значения — строки, структурированные объекты (карта подключей и значений, сливаемая по каждому подключу с унаследованным структурированным значением) или null; явный null для ключа, унаследованного от родительской подсистемы, удаляет унаследованную привязку из этого компонента (отказ от Feature через аннотации). Аннотации уровня Component переопределяют унаследованные аннотации уровня подсистемы по каждому ключу; соседние компоненты в той же подсистеме сохраняют свои собственные карты аннотаций независимо друг от друга. |
values | object | нет | Непрозрачные когнитивные свойства, передаваемые сущности Component и проверяемые по её схеме. |
uses | component_uses_block | нет | Соединения, которые компонент проводит к компонентам, от которых он зависит, с ключами по сокетам. Каждый сокет перечисляет свои цели или называет каждое соединение под псевдонимом. Соединение, названное под псевдонимом, может содержать значения разработчика для этого соединения и вложения, заполняющие слоты, объявленные сокетом. |
inject | inject_block | нет | Самовнедрение на уровне компонента. Внедряет собственные значения компонента (через ‘value:’) или его собственные ключи provides (через ‘from:’) напрямую в канал доставки (.context.inject). Допускается, только если сущность каталога Component объявляет ‘spec.inject’ с соответствующими механизмами. Ключ inject, совпадающий с ключом, объявленным в uses[].inject, останавливает сборку как дублирующийся ключ доставки в разных источниках inject. |
features | map of object | нет | Features, подключённые к этому компоненту, с ключами по имени экземпляра, которое автор даёт каждому вложению. Это единственное место подключения: операционная Feature, Feature учётных данных (с меткой feature.aggrega.ai/kind: secret) и Feature идентичности подключаются здесь, с одним и тем же ключевым словом и в одной и той же форме. Различаются они тем, что создаёт вложение, а не тем, как оно объявлено. Вложение, имя экземпляра которого совпадает со слотом, объявленным сущностью Component в featuresSchema, заполняет этот слот; любое другое имя экземпляра означает свободное вложение. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.