Поверхня публікації
Кожен YAML каталогу Aggrega містить уніфікований набір полів метаданих, що описують сутність для розповсюдження через каталог: хто її супроводжує, під якою ліцензією вона постачається, де розміщено її вихідний код, за якими ключовими словами її можна знайти. Разом ці поля утворюють поверхню публікації — словник метаданих, на який спираються видавці каталогів і споживачі-інструменти; він відрізняється від механізму metadata.labels / metadata.annotations з боку вмісту, описаного в labels-and-annotations.md.
На цій сторінці описано поля поверхні публікації, перелік полів опису в корпусі (описи оболонки, екземпляра та рівня поля), призначення поля супровідника та його перевіреного споживача, а також асиметрії обов’язкових полів для кожної сутності (які поля кожна сутність вимагає сьогодні та де ці асиметрії навмисні).
Поля поверхні публікації
Наведені нижче поля є в кожній сутності домену 2 (Component, Feature) і домену 3 (Recipe, FeatureRecipe, Plugin), а також в Aggregate як багаторазовому модулі. Вони є також у Manifest і Release, але зі звуженою семантикою (атрибуція робочого простору, а не публікація в каталозі).
| Поле | Тип | Призначення | Споживач |
|---|---|---|---|
description | string | Зрозумілий людині короткий опис сутності | Картки підказок у редакторі (aggrega serve); інструмент describe, який викликає асистент (aggrega mcp); анотація для пошуку в опублікованому артефакті (aggrega push); aggrega inspect |
maintainers | масив об’єктів | Хто володіє сутністю (ім’я, email, url) | Повузловий catalog_metadata в IR, на вузлах Component |
license | string | Юридична відповідність (зазвичай ідентифікатор SPDX) | Повузловий catalog_metadata в IR, на вузлах Component |
repository | string (URL) | Git-репозиторій, де зберігається вихідний код | Повузловий catalog_metadata в IR, на вузлах Component — більше ніщо його не читає |
home | string (URL) | URL документації / вікі | Повузловий catalog_metadata в IR, на вузлах Component — більше ніщо його не читає |
keywords | масив рядків | Теги для пошуку | Повузловий catalog_metadata в IR, на вузлах Component — жоден пошуковий індекс їх не використовує |
Усі шість полів необов’язкові в кожній сутності, що їх містить. Автор каталогу, який пропускає весь набір, отримує валідний YAML — поверхня публікації призначена для сутностей, що поширюються через каталог; сутності для внутрішнього використання можуть її пропустити без наслідків.
Стовпець «Споживач» вичерпно описує те, що постачається сьогодні, і два його наслідки варто назвати прямо, бо вони змінюють те, що варто писати:
description— єдине поле, яке має більше ніж одного читача.aggrega serveвиводить його в картці підказки для Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest і чотирьох видів бібліотек (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary) — але не для Plugin чи Release. Інструментdescribe, який надаєaggrega mcp, повертає його для сутності будь-якого виду.aggrega pushдодає його до опублікованого артефакту як анотацію для пошуку.aggrega inspectдрукує його під заголовком сутності для кожного виду і не друкує жодного іншого поля поверхні публікації.repository,homeіkeywordsперевіряються й переносяться, але поза IR їх ніщо не читає. Жодна поверхня переліку, сайт каталогу чи пошуковий індекс їх не використовує. Заповнюючи їх, ви записуєте походження, яке супроводжує сутність і доступне для читання з виводу IR та з політики керування; це не робить сутність знаходжуваною будь-де.
Застарілість не є полем поверхні публікації. Сутність позначають застарілою, записуючи для неї маркер у реєстрі після публікації — підписаний маркер із рівнем серйозності (warning, error або retracted), причиною та заміною, що перевіряється під час завантаження. Тоді про нього повідомляє кожна поверхня, яка читає lock-файл; build.halt_on_deprecated_severity вирішує лише те, чи він також зупиняє збирання. Маркер ніколи не записують у власному YAML сутності, і причина структурна: опублікований артефакт незмінний, тож прапорець, зафіксований у ньому під час публікації, ніколи не зміг би виразити рішення, ухвалене пізніше. Повідомлення про застарілість, яке aggrega inspect друкує для сутності каталогу, береться з маркера — для кожного виду, який він розв’язує за назвою.
Використання в IR — повузловий catalog_metadata
Компілятор переносить поля поверхні публікації з кожного Component у блок catalog_metadata відповідного вузла, видимий у графі IR, який повертає запуск (aggrega inspect <release> --ir-graph). Блок містить maintainers, license, repository, home і keywords — п’ять полів, які переносить IR; description серед них немає. Інструменти, побудовані на контракті графа IR, читають метадані звідти, а не перечитують YAML каталогу.
Лише вузли Component. Блок заповнюється пошуком типу компонента вузла в каталозі як Component, тож поверхня публікації сутностей Feature, Recipe, FeatureRecipe чи Plugin ніколи не потрапляє до IR — ці сутності містять поля, і поля проходять перевірку, але жоден вузол IR із них не утворюється.
catalog_metadata повністю зникає з JSON IR, коли кожне поле поверхні публікації у вихідному Component порожнє або нульове: блок пропускається, а не виводиться з порожніми значеннями. Тому той самий вхід дає той самий компактний вивід, що зберігає стабільність diff IR між запусками.
Політика керування може читати цей блок. Плагін, підключений у plugins.governance в ролі ir-verdict, отримує весь граф IR, вузол за вузлом, включно з catalog_metadata кожного вузла Component — тож політика може прийняти або відхилити збирання за license, repository, home, keywords або maintainers вузла. Такий доступ властивий лише сокету керування: плагін рендерингу провайдера отримує обмежену повузлову проєкцію без catalog_metadata, тож плагіни рендерингу не можуть читати ці поля.
Три типи описів
Поле description однаково присутнє в обгортці, але корпус також містить рядки-описи всередині оголошень схем (описи окремих полів) і всередині тіл стовпів (описи окремих екземплярів). Співіснують три різні типи описів; таблиця нижче розрізняє їх.
| Тип | Де розташований | Автор | Призначення |
|---|---|---|---|
| Опис обгортки | metadata.description у кожній сутності | Видавець каталогу | Підсумок сутності загалом, що показується в спливних картках редактора та проставляється на опублікований артефакт |
| Опис екземпляра | Поле description поруч з оголошенням окремого екземпляра (наприклад, featuresSchema.<slot>.description, usesSchema.<socket>.description) | Автор схеми | Опис окремого слота / сокета / порту для авторів сутностей-споживачів, які читають оголошення |
| Опис поля | Анотація JSON Schema 2020-12 description: у вмісті schema: / featuresSchema: / usesSchema: (компактна форма або повний YAML JSON Schema) | Автор схеми | Документація окремих полів, що супроводжує схему |
Три типи мають спільне слово «description», але розташовані на структурно різних рівнях. Опис обгортки стосується сутності загалом; опис екземпляра стосується оголошення всередині слота схеми; опис поля стосується конкретного значення всередині типізованої схеми. Автори, які пишуть сутність Component:
- Задайте
metadata.descriptionодин раз для самої сутності Component. - Задайте
featuresSchema.admin_password.descriptionодин раз для кожного слота облікових даних, який оголошує Component. - Задайте анотації
description:для окремих полів усередині блокуschema:— у компактній формі (port: { type: integer, description: "..." }) або в повному YAML JSON Schema, — щоб задокументувати кожне поле для тих, хто читає схему сутності Component.
Три типи не каскадуються й не конфліктують, і кожен потрапляє на іншу поверхню — або на жодну:
- Опис обгортки — спливні картки редактора, анотації для пошуку на опублікованому артефакті та
aggrega inspect, згідно зі стовпцем «Споживач» вище. - Опис поля — дослівно з’являється у фрагменті схеми, який відображає спливна картка сутності Component або Feature. Фрагмент охоплює лише
spec.schemaі обрізається до початкових рядків, тому опис глибше в блоці — або опис усерединіfeaturesSchema:чиusesSchema:— там не з’являється. - Опис екземпляра — оголошується й супроводжує сутність; жодна наявна поверхня не відображає його окремо.
aggrega inspectперелічує сокети та слоти функцій сутності Component без їхніх описів.
Призначення поля maintainers
Поле maintainers містить масив об’єктів, кожен з яких має name, email і url. Призначення поля та його перевірений споживач:
Призначення (інформаційне + походження в IR). Поле має інформаційний характер для публікації каталогу: архітектурний задум — «хто відповідає за цю сутність каталогу», тобто сигнал про власника, що супроводжує сутність. Жодна поверхня не подає його як список контактів, і жодна вбудована перевірка ні з чим його не порівнює.
Перевірений споживач (catalog_metadata для кожного вузла). Компілятор переносить metadata.maintainers кожної сутності Component у catalog_metadata.maintainers відповідного вузла в IR; це видно в графі, який повертає aggrega inspect <release> --ir-graph, якщо вихідна сутність Component оголосила це поле. Це єдиний читач поля. Політика керування, підключена в plugins.governance у ролі ir-verdict, бачить його там, тож правило щодо власника — кожна сутність називає щонайменше одного супровідника, домен супровідника належить до затвердженого набору — можна виразити щодо IR, а не щодо YAML каталогу. Жодне таке правило не постачається; сокет — це місце для нього.
Компілятор не примушує до дотримання і не перевіряє вміст супровідників понад структурну форму JSON Schema (name обов’язкове; email і url необов’язкові, обидва — рядки). Чи справді вказані супровідники володіють сутністю, чи доступна їхня електронна адреса, чи підписано коміт у репозиторії кимось із них — це питання керування каталогом, і жодна постачена перевірка нічого з цього не оцінює. Вони належать до політики керування, яку підключає оператор, а не до компілятора.
Асиметрії обов’язкових полів
Види сутностей Aggrega мають дещо різні набори обов’язкових полів у своїх JSON Schema. Більшість асиметрій навмисні й відображають роль сутності.
Обов’язкові поля для кожної сутності (без apiVersion / kind / metadata.name / metadata.version, які однаково обов’язкові для всіх сутностей):
| Сутність | Додаткові обов’язкові поля | Обґрунтування |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Вимога щодо мітки критична для зіставлення селекторів: анотації usesSchema x-aggrega-selector: фільтрують цільові Components за цією міткою; без неї сутність Component відхиляється під час завантаження |
| Feature | — | Немає вимоги щодо зарезервованої мітки; Features ідентифікуються за назвою та видавцем |
| Recipe | spec.capability, spec.implements | Можливість керує диспетчеризацією провайдера; implements керує прив’язкою до сутності Component |
| FeatureRecipe | spec.capability, spec.implements | Так само, як для Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | Тип сокета, який реалізує плагін (частина блоку адресації, що задає сегмент <pluginType> похідної координати plugin/<pluginType>/<name>), і версія ABI, на яку він розрахований; розташування .wasm виводиться з цієї ідентичності, а не задається автором; плагін рендерингу провайдера (pluginType: provider) додатково містить свій контракт трансляції в spec.provider |
| Aggregate | — | Aggregate, що не оголошує жодного з components, subsystems чи aggregates, завантажується й збирається, але нічого не рендерить |
| Manifest | spec.mappings | Рівні зіставлення — єдине призначення сутності Manifest |
| Release | spec.aggregate, spec.manifest (Release, що оголошує extends, не записує aggregate і може пропустити manifest); metadata.environment | Перші два прив’язують збірку до конкретних Aggregate та Manifest; environment проставляється у відрендерений вивід як мітка aggrega.ai/environment |
Вимога щодо мітки Component є критичною
Мітка component.aggrega.ai/type — єдина мітка, яку Aggrega вимагає для будь-якої сутності. Вимога існує тому, що механізм usesSchema стандартної бібліотеки фільтрує цільових кандидатів через анотації x-aggrega-selector: з рядками селекторів на кшталт "component.aggrega.ai/type=database" — селектор звіряється з мітками цілі, щоб визначити, чи відповідає тип прийнятним типам сокета. Схема Component забезпечує це: Component без цієї мітки відхиляється під час завантаження (E0215) із зазначенням відсутнього ключа.
Отже, ця вимога стосується не поверхні публікації (мітка не призначена для пошуку в каталозі), а топології: її має кожен Component, зокрема Components для внутрішнього використання, не призначені для поширення через каталог.
Поле metadata.environment сутності Release обов’язкове
Схема Release вимагає metadata.environment — рядок, який збірка проставляє у відрендерений вивід як мітку aggrega.ai/environment.
Інші асиметрії
Решта асиметрій (обов’язкові поля Recipe порівняно з Component, вимога mappings для Manifest) відображають роль кожної сутності. Автори, які хочуть однакового контракту обов’язкових полів для всіх видів сутностей, його не знайдуть; асиметрії навмисні згідно з дизайном, що ґрунтується на ролях.
Перехресні посилання
labels-and-annotations.md— механізм метаданих на боці вмісту, що доповнює поверхню публікації.entities/component.md— вимогаmetadata.labels.component.aggrega.ai/typeсутності Component та оголошенняschema/usesSchema/featuresSchema.entities/release.md— полеmetadata.environmentсутності Release та вимога щодо нього.10-status.md— стан оболонки метаданих.architecture/02-ecosystem-philosophy.md— суворе розмежування API та концепція дизайну Enterprise Metadata Suite.architecture/13-catalog-and-registry.md§«Lockfile pinning and artifact immutability» + §«Catalog entity name-shape enforcement» — що правило незмінності відхиляє під час публікації і де перевіряються форми імен для кожного виду сутностей: плагін дисципліни публікації повідомляє про них у рекомендаційному порядку, коли автор запускаєaggrega lint, а ні збирання, ні публікація їх не перевіряють.architecture/11-governance-and-compliance.md§«Inheritance and publishing discipline» — які правила керування належать плагіну дисципліни публікації, а які натомість вирішує за побудовою успадкування в розширювальній сутності Component.