Схема Aggrega Catalog (Component)
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/component-v1beta1.schema.json
Абстрактное определение атомарного строительного блока.
Пояснения по созданию сущностей Component см. в справочнике по созданию сущностей Component; на этой странице описана структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “Component” | да | Константа: "Component" |
metadata | object | да | |
spec | object | да | Определения валидации и схемы, управляющие непрозрачной полезной нагрузкой значений разработчика. |
Дополнительные свойства не допускаются.
component.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
version | string | да | Версия интерфейса по строгому семантическому версионированию (например, 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 | да | Метки для утиной типизации, объявляющие характеристики. Должны включать зарезервированный ключ ‘component.aggrega.ai/type’. |
annotations | map of string | нет | Неизменяемые, внутренне присущие характеристики компонента, задаваемые архитектором платформы в домене 2. Каскадно передаются в область .context.annotations.catalog. |
Дополнительные свойства не допускаются.
component.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
component.metadata.labels
Метки для утиной типизации, объявляющие характеристики. Должны включать зарезервированный ключ ‘component.aggrega.ai/type’.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | да | Зарезервированная ось, указывающая, чем является этот компонент. Aggrega определяет этот ключ и допустимые для него значения, поэтому набор закрыт; чтобы классифицировать компоненты по собственной оси, добавьте собственный ключ метки рядом с этим. Допустимые значения: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Определения валидации и схемы, управляющие непрозрачной полезной нагрузкой значений разработчика.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
extends | string | нет | URI базовой сущности Component, которую расширяет эта сущность Component. Расширение компонует структуру: метки и аннотации метаданных базы, её слоты подключения (featuresSchema), её список разрешённых механизмов самовнедрения (inject) и её сокеты топологии (usesSchema) наследуются, и эта сущность Component может дополнять их или заменять унаследованную запись ключ за ключом. Столпы данных базы НЕ компонуются: блок schema базы наследуется в точности так, как его написал автор базы, поэтому расширяющая сущность Component пишет schema: inherited и не задаёт собственного содержимого столпов. |
featuresSchema | map of object | нет | Декларативные определения слотов подключения: именованные точки привязки, в которых эта сущность ожидает подключения сущности Feature. Слот ограничивает, какое заполнение может к нему привязаться (selector) и как может доставляться материал заполнения (inject); собственная сущность Feature заполнения владеет своими значениями и инфраструктурным контрактом. Объявление слота никогда не закрывает блок подключений: автор может подключить сущность Feature под именем, которое не объявлено ни одним слотом, так что одна сущность обслуживает и подключение через слот, и учётные данные, общие для более широкой области. Слот — это точка привязки, а не сокет зависимости: отдельную поверхность топологии объявляет usesSchema. |
inject | string[] | нет | Разрешённые механизмы доставки при самовнедрении (например, [‘env’, ‘file’, ‘arg’]). Если поле задано, разработчики могут использовать блок inject: на уровне компонента в сущности Aggregate, чтобы внедрять собственные значения или ключи provides непосредственно в канал доставки. Если поле опущено, самовнедрение на уровне компонента запрещено (шаблон «чёрного ящика»: сущность Recipe выполняет всё внутреннее связывание). Семантика та же, что у usesSchema[].inject, но управляет собственными значениями компонента, а не межкомпонентной топологией. Можно указать любое имя механизма, кроме all, которое не может назвать ни один блок inject. |
usesSchema | map of object | нет | Сокеты зависимостей, которые объявляет эта сущность, с именем сокета в качестве ключа; каждое соединение, проведённое через сокет, проверяется на соответствие объявлению этого сокета — его селектору, допустимым механизмам inject и контрактам для каждого соединения. Ключи: одна или несколько букв, цифр, символов подчёркивания или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
schema | любой | нет | Содержимое JSON Schema 2020-12, описывающее столпы свободной формы: values (область разработчика — параметры формы приложения, которые разработчик настраивает для каждого экземпляра Component в Aggregate); infra (область оператора — физические параметры размеров, задаваемые Release); и provides (ключи нисходящего контекста, которые этот Component предоставляет потребителям через канал топологии). Поддерживаются четыре режима написания, выбираемые по форме содержимого: (1) встроенное содержимое (YAML-карта в компактной форме, в виде JSON Schema YAML или в смешанном виде); (2) замена файлом через {$import: |
assertions | map of string | нет | Межполевая валидация во время сборки. Каждая запись — именованное утверждение: ключ — стабильный идентификатор правила, выводимый в сообщениях об ошибках; значение — строка шаблона Go с семантикой остановки {{ fail "message" }}. Несколько именованных утверждений одной сущности вычисляются для каждого экземпляра в порядке, объявленном автором; первое неудачное утверждение останавливает сборку. Утверждения Component вычисляются после разрешения и статического анализа, до рендеринга, и выражают архитектурные инварианты контракта, которые выполняются независимо от того, какая сущность Recipe привязывается. Контекст шаблона: .values / .infra / .uses / .features / .metadata. Вычислитель использует missingkey=error: ссылки на неопределённые ключи останавливают сборку с диагностикой no-such-key. Поскольку голая ссылка останавливает сборку раньше, чем может сработать запасное значение, простой default не обеспечивает запасного значения для необязательного поля на этой поверхности: защитите ссылку с помощью hasKey или используйте вспомогательную функцию optional, которая сама выполняет проверку наличия. Чтение ключа через index тоже его не обеспечивает: index останавливает сборку на ключе, которого нет в карте, называя этот ключ. Наследование аддитивно: сущность Component, объявляющая extends, проверяется как по унаследованным утверждениям, так и по собственным, причём унаследованные правила идут первыми, а цепочка любой глубины накапливает их от корня вниз, поэтому, если не выполняется более одного правила, сообщается то, которое объявлено выше всего в цепочке. Повторное использование унаследованного имени для объявления другого правила отклоняется при разрешении цепочки extends по каталогу с указанием обеих сущностей Components и общего имени, поэтому ошибка проявляется, когда базовая сущность Component присутствует, а не по одному лишь расширяющему документу; расширяющая сущность Component добавляет правила и никогда не заменяет их. Повторение унаследованного правила байт в байт под его же именем принимается как пустая операция, которой оно и является. Ничто не проверяет, могут ли два правила выполняться одновременно: взаимно невыполнимая пара — это ошибка автора, которая проявляется как обычный сбой утверждения, когда экземпляр нарушает то из них, что срабатывает первым, и никогда не выдаётся заранее как предупреждение. |
Дополнительные свойства не допускаются.
Определения
extending-component-must-declare-schema-inherited
Применяется, когда задан spec.extends. Расширяющая сущность Component получает values / infra / provides своей базы ровно в том виде, в каком их написала база, поэтому она объявляет spec.schema: inherited и не пишет собственного содержимого столпов. Оба других варианта являются ошибками, причём это разные ошибки: полное отсутствие spec.schema, из-за которого читатель не сможет отличить унаследованный блок столпов от забытого, и содержимое столпов под spec.schema, которое запрашивало бы второй, расходящийся контракт для сущности Component, контрактом которой является контракт её базы.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
schema | const “inherited” | да | Маркер наследования и единственное значение, которое spec.schema принимает в сущности Component, объявляющей extends. Он указывает, откуда берутся столпы; само содержимое столпов принадлежит базовой сущности Component. Константа: "inherited" |
non-extending-component-authors-its-own-schema
Применяется, когда spec.extends отсутствует. Сущность Component, которая не расширяет никакую базу, пишет собственное содержимое values / infra / provides под spec.schema, поэтому поле содержит написанное автором содержимое, а не маркер inherited: маркер означает, что столпы берутся из базы, а у этой сущности Component базы нет.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
schema | object | нет | Написанное автором содержимое столпов — словарь в любом из трёх режимов написания содержимого, описанных в spec.schema. |