Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Схема Aggrega Catalog (Component)

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.

Ідентифікатор схеми: https://aggrega.ai/schemas/component-v1beta1.schema.json

Абстрактне визначення атомарного будівельного блоку.

Описові вказівки щодо створення сутностей Component див. у довіднику зі створення сутностей Component; ця сторінка документує структурну схему, яку описує той довідник.

Тип верхнього рівня: object

Властивості

ВластивістьТипОбов’язковаОпис
apiVersionconst “aggrega.ai/v1beta1”такКонстанта: "aggrega.ai/v1beta1"
kindconst “Component”такКонстанта: "Component"
metadataobjectтак
specobjectтакВизначення валідації та схеми, що керують непрозорим корисним навантаженням values розробника.

Додаткові властивості не дозволені.

component.metadata

ВластивістьТипОбов’язковаОпис
namestringтакЩонайменше 1 символ.
versionstringтакСтрога семантична версія інтерфейсу (наприклад, 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-]+)*))?$.
descriptionstringніЩо це за сутність і для чого вона призначена — для того, хто вирішує, чи використовувати її. Почніть із речення, що називає її, а потім додайте те, що потрібно читачеві, щоб вибрати її та правильно використовувати: чого вона очікує від сутності Release, яка її розгортає, і все несподіване в її поведінці. Зазвичай достатньо короткого абзацу.
maintainersobject[]ніСписок супровідників, яким належить ця сутність.
licensestringніІдентифікатор SPDX ліцензії програмного забезпечення, яке описує ця сутність, наприклад MIT або AGPL-3.0. Він фіксує умови цього програмного забезпечення, а не умови цього файлу.
repositorystringніURL репозиторію Git, де зберігаються вихідні файли.
homestringніURL домашньої сторінки, вікі або документації цієї сутності.
keywordsstring[]ніСписок описових ключових слів для зручного пошуку в інтерфейсі.
labelsobjectтакМітки для качиної типізації, що оголошують характеристики. Мають містити зарезервований ключ ‘component.aggrega.ai/type’.
annotationsmap of stringніНезмінні, внутрішні характеристики компонента, які задає Platform Architect у Domain 2. Каскадно передаються до контейнера .context.annotations.catalog.

Додаткові властивості не дозволені.

component.metadata.maintainers[]
ВластивістьТипОбов’язковаОпис
namestringтак
emailstringні
urlstringні

Додаткові властивості не дозволені.

component.metadata.labels

Мітки для качиної типізації, що оголошують характеристики. Мають містити зарезервований ключ ‘component.aggrega.ai/type’.

ВластивістьТипОбов’язковаОпис
component.aggrega.ai/typestring (enum)такЗарезервована вісь, що визначає, яким є цей компонент. Aggrega визначає цей ключ і значення, які він приймає, тож набір закритий; щоб класифікувати компоненти за власною віссю, додайте власний ключ мітки поряд із цим. Допустимі значення: "server", "worker", "task", "function", "stateful-server", "resource"

component.spec

Визначення валідації та схеми, що керують непрозорим корисним навантаженням values розробника.

ВластивістьТипОбов’язковаОпис
extendsstringніURI базової сутності Component, яку розширює ця сутність Component. Розширення компонує структуру: мітки й анотації метаданих бази, її слоти прикріплення (featuresSchema), її список дозволених механізмів самоін’єкції (inject) та її топологічні сокети (usesSchema) успадковуються, і ця сутність Component може доповнювати їх або замінювати успадкований запис ключ за ключем. Стовпи даних бази НЕ компонуються — блок schema бази успадковується точно так, як його написала база, тому сутність Component, що розширює іншу, пише schema: inherited і не задає власного вмісту стовпів.
featuresSchemamap of objectніДекларативні визначення слотів прикріплення: іменовані точки зв’язування, у яких ця сутність очікує прикріплення сутності Feature. Слот обмежує, яке заповнення може його зв’язати (selector) і як може доставлятися матеріал заповнення (inject); власна сутність Feature заповнення володіє своїми values та контрактом infra. Оголошення слота ніколи не закриває блок прикріплень — автор може прикріпити сутність Feature під іменем, яке не оголошує жоден слот, тож одна сутність слугує і прикріпленням через слот, і обліковими даними, спільними в ширшій області. Слот — це точка зв’язування, а не сокет залежності: usesSchema оголошує окрему топологічну поверхню.
injectstring[]ніДозволені механізми доставки самоін’єкції (наприклад, [‘env’, ‘file’, ‘arg’]). Якщо поле присутнє, розробники можуть використовувати блок inject: на рівні компонента в сутності Aggregate, щоб ін’єктувати власні values або ключі provides безпосередньо в канал доставки. Якщо поле пропущено, самоін’єкцію на рівні компонента заборонено (патерн Black-Box — сутність Recipe виконує все внутрішнє зв’язування). Та сама семантика, що й у usesSchema[].inject, але керує власними values компонента, а не міжкомпонентною топологією. Можна вказати будь-яку назву механізму, крім all, яку не може назвати жоден блок inject.
usesSchemamap of objectніСокети залежностей, які оголошує ця сутність, з назвою сокета як ключем; кожне з’єднання, проведене через сокет, перевіряється щодо оголошення цього сокета — його селектора, дозволених механізмів inject і контрактів для кожного з’єднання. Ключі: одна або більше літер, цифр, підкреслень чи дефісів. Крапка не дозволена. Шаблон: ^[a-zA-Z0-9_-]+$.
schemaanyніВміст JSON Schema 2020-12, що охоплює стовпи довільної форми: values (домен розробника — параметри форми застосунку, які розробник налаштовує для кожного екземпляра Component в сутності Aggregate); infra (домен оператора — фізичні параметри розміру, що надаються сутністю Release); і provides (низхідні ключі контексту, які ця сутність Component надає споживачам через топологічний канал). Приймає чотири режими написання через диспетчеризацію за формою вмісту: (1) вбудований вміст (мапа YAML у компактній формі, JSON Schema YAML або змішана); (2) заміна файлом через {$import: }, записана в spec.schema, щоб надати весь контракт з одного файлу, або в окремому стовпі, щоб надати лише цей стовп, причому відносний шлях читається відносно каталогу, що містить сутність, яка його оголосила; (3) міждокументне посилання через {$ref: #/schemas/} на запис сутності SchemaLibrary за ідентичністю голого імені (версію надає lockfile кожної сутності Release; у посиланні не з’являється хост реєстру); (4) голий рядок inherited — єдина форма, яку може писати сутність Component, що оголошує extends: вона вказує, що три стовпи походять від базової сутності Component точно так, як їх написала база. Режими 1–3 задають вміст і доступні лише сутності Component, що не оголошує extends; режим 4 не задає вмісту й обов’язковий для кожної сутності Component, що його оголошує. Супутні поля usesSchema та featuresSchema охоплюють стовпи фіксованої форми (сокети залежностей, слоти прикріплення); компілятор компонує ці три в одну схему, за якою перевіряється екземпляр.
assertionsmap 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, чиїм контрактом є контракт її бази.

ВластивістьТипОбов’язковаОпис
schemaconst “inherited”такМаркер успадкування і єдине значення, яке приймає spec.schema у сутності Component, що оголошує extends. Він вказує, звідки походять стовпи; сам вміст стовпів належить базовій сутності Component. Константа: "inherited"

non-extending-component-authors-its-own-schema

Застосовується, коли spec.extends відсутнє. Сутність Component, яка не розширює жодної бази, пише власний вміст values / infra / provides у spec.schema, тому поле містить написаний вміст, а не маркер inherited: маркер означає, що стовпи походять із бази, а в цієї сутності Component бази немає.

ВластивістьТипОбов’язковаОпис
schemaobjectніНаписаний вміст стовпів — мапа в будь-якому з трьох режимів написання вмісту, які документує spec.schema.