Схема 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 | так | Визначення валідації та схеми, що керують непрозорим корисним навантаженням values розробника. |
Додаткові властивості не дозволені.
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 | ні | Незмінні, внутрішні характеристики компонента, які задає Platform Architect у Domain 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
Визначення валідації та схеми, що керують непрозорим корисним навантаженням values розробника.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
extends | string | ні | URI базової сутності Component, яку розширює ця сутність Component. Розширення компонує структуру: мітки й анотації метаданих бази, її слоти прикріплення (featuresSchema), її список дозволених механізмів самоін’єкції (inject) та її топологічні сокети (usesSchema) успадковуються, і ця сутність Component може доповнювати їх або замінювати успадкований запис ключ за ключем. Стовпи даних бази НЕ компонуються — блок schema бази успадковується точно так, як його написала база, тому сутність Component, що розширює іншу, пише schema: inherited і не задає власного вмісту стовпів. |
featuresSchema | map of object | ні | Декларативні визначення слотів прикріплення: іменовані точки зв’язування, у яких ця сутність очікує прикріплення сутності Feature. Слот обмежує, яке заповнення може його зв’язати (selector) і як може доставлятися матеріал заповнення (inject); власна сутність Feature заповнення володіє своїми values та контрактом infra. Оголошення слота ніколи не закриває блок прикріплень — автор може прикріпити сутність Feature під іменем, яке не оголошує жоден слот, тож одна сутність слугує і прикріпленням через слот, і обліковими даними, спільними в ширшій області. Слот — це точка зв’язування, а не сокет залежності: usesSchema оголошує окрему топологічну поверхню. |
inject | string[] | ні | Дозволені механізми доставки самоін’єкції (наприклад, [‘env’, ‘file’, ‘arg’]). Якщо поле присутнє, розробники можуть використовувати блок inject: на рівні компонента в сутності Aggregate, щоб ін’єктувати власні values або ключі provides безпосередньо в канал доставки. Якщо поле пропущено, самоін’єкцію на рівні компонента заборонено (патерн Black-Box — сутність Recipe виконує все внутрішнє зв’язування). Та сама семантика, що й у usesSchema[].inject, але керує власними values компонента, а не міжкомпонентною топологією. Можна вказати будь-яку назву механізму, крім all, яку не може назвати жоден блок inject. |
usesSchema | map of object | ні | Сокети залежностей, які оголошує ця сутність, з назвою сокета як ключем; кожне з’єднання, проведене через сокет, перевіряється щодо оголошення цього сокета — його селектора, дозволених механізмів inject і контрактів для кожного з’єднання. Ключі: одна або більше літер, цифр, підкреслень чи дефісів. Крапка не дозволена. Шаблон: ^[a-zA-Z0-9_-]+$. |
schema | any | ні | Вміст 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. |