Schemat Aggrega Developer Intent (Aggregate)
Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.
Identyfikator schematu: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
Rekurencyjna, sparametryzowana architektura AI. Pełni zarówno rolę korzenia budowania, jak i modułu wielokrotnego użytku.
Wskazówki dotyczące tworzenia encji Aggregate opisowo przedstawia dokumentacja tworzenia encji Aggregate; ta strona dokumentuje schemat strukturalny, który ta dokumentacja opisuje.
Typ najwyższego poziomu: object
Właściwości
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | tak | Stała: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | tak | Stała: "Aggregate" |
metadata | object | tak | |
defs | string[] | nie | Opcjonalny blok na standardowe kotwice YAML (& i *), pozwalający zachować zasadę DRY w encji Aggregate przy jednoczesnym utrzymaniu płaskiego słownika O(1) dla kompilatora. Odpowiada analogicznemu blokowi w encji Manifest. |
spec | object | tak | Powierzchnia Developer Intent: globalny kontrakt parametrów, importy zagnieżdżonych agregatów, publiczne API eksportowanych komponentów, grupowania podsystemów oraz instancje komponentów tworzące moduł. |
Dodatkowe właściwości są niedozwolone.
aggregate.metadata
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Co najmniej 1 znak. |
version | string | tak | Wersja modułu aggregate w ścisłym formacie Semantic Versioning. Wzorzec: ^(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 | nie | |
maintainers | object[] | nie | Lista opiekunów, do których należy ta encja. |
license | string | nie | Identyfikator SPDX licencji oprogramowania opisywanego przez tę encję, np. MIT lub AGPL-3.0. Określa warunki tego oprogramowania, a nie warunki tego pliku. |
repository | string | nie | URL repozytorium Git, w którym znajdują się pliki źródłowe. |
home | string | nie | URL strony domowej, wiki lub dokumentacji tej encji. |
keywords | string[] | nie | Lista opisowych słów kluczowych ułatwiających wyszukiwanie w interfejsie użytkownika. |
labels | mapa string | nie | Etykiety duck typing na poziomie modułu, służące do wyszukiwania w katalogu, ewaluacji polityk i filtrowania w Studio/IDE. Etykiety te opisują tożsamość encji Aggregate jako modułu wielokrotnego użytku (np. aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). NIE są one przekazywane kaskadowo do podrzędnych węzłów komponentów — etykiety komponentów pochodzą wyłącznie z encji katalogowej Component w Domenie 2. |
Dodatkowe właściwości są niedozwolone.
aggregate.metadata.maintainers[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | |
email | string | nie | |
url | string | nie |
Dodatkowe właściwości są niedozwolone.
aggregate.spec
Powierzchnia Developer Intent: globalny kontrakt parametrów, importy zagnieżdżonych agregatów, publiczne API eksportowanych komponentów, grupowania podsystemów oraz instancje komponentów tworzące moduł.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
parameters | mapa object | nie | Globalny kontrakt środowiskowy. Każdy wpis jest obiektem kontraktu typowanego, zapisanym w podzbiorze słownictwa formy kompaktowej (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). Strukturę zagnieżdżoną wyraża się za pomocą pola podrzędnego properties: formy typowanej. Wypełnienie w encji Release może być wpisane bezpośrednio (parameters: {…}) lub zaimportowane z pojedynczego pliku (parameters: {$import: |
aggregates | mapa object | nie | Zagnieżdżone agregaty pełniące rolę importowanych modułów. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
exportedComponents | mapa string | nie | Interfejs publicznego API. Mapuje udostępnianą nazwę publiczną na wewnętrzny identyfikator komponentu. Nadrzędne encje Aggregates importujące ten moduł odwołują się do komponentów za pomocą tych nazw publicznych. |
subsystems | mapa subsystem | nie | Nazwane logiczne grupowania komponentów encji Aggregate w podsystemy. Wzajemnie wykluczają się z komponentami najwyższego poziomu — zadeklarowanie obu jest odrzucane. Podsystem, któremu autor nada nazwę default, jest zwykłym zadeklarowanym podsystemem, odrębnym od syntetycznego podsystemu default tworzonego przez kompilator dla encji Aggregate zawierającej wyłącznie komponenty. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
components | mapa component_instance | nie | Mapa logicznych, atomowych komponentów tworzących tę encję Aggregate, definiowanych bezpośrednio na najwyższym poziomie. Komponenty najwyższego poziomu i podsystemy wzajemnie się wykluczają — zadeklarowanie obu jest odrzucane. Gdy komponenty są zdefiniowane tutaj (bez podsystemów), kompilator podczas ładowania umieszcza je w syntetycznym podsystemie default, a IR oznacza ten podsystem jako syntetyczny. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
Dodatkowe właściwości są niedozwolone.
Definicje
inject_delivery
Pojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (lokalny identyfikator — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub niestandardowy klucz specyficzny dla mechanizmu) oraz dokładnie jedno z pól: ‘from’ (klucz provides do rozwiązania) albo ‘value’ (literał tekstowy, opcjonalnie zawierający wyrażenia szablonów Go ewaluowane przy rozwiązywaniu self-inject). ‘from’ jest rozwiązywane względem provides celu w kontekście uses[].inject, względem provides publikowanych przez encję FeatureRecipe dołączenia w kontekście features.
Typ: object[]
inject_block
Agnostyczne trasowanie wstrzykiwania. Mapuje zmienne lokalne na klucze provides celu (uses[].inject), na klucze provides publikowane przez encję FeatureRecipe dołączenia (features.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
env | inject_delivery | nie | Pojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (lokalny identyfikator — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub niestandardowy klucz specyficzny dla mechanizmu) oraz dokładnie jedno z pól: ‘from’ (klucz provides do rozwiązania) albo ‘value’ (literał tekstowy, opcjonalnie zawierający wyrażenia szablonów Go ewaluowane przy rozwiązywaniu self-inject). ‘from’ jest rozwiązywane względem provides celu w kontekście uses[].inject, względem provides publikowanych przez encję FeatureRecipe dołączenia w kontekście features. |
file | inject_delivery | nie | Pojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (lokalny identyfikator — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub niestandardowy klucz specyficzny dla mechanizmu) oraz dokładnie jedno z pól: ‘from’ (klucz provides do rozwiązania) albo ‘value’ (literał tekstowy, opcjonalnie zawierający wyrażenia szablonów Go ewaluowane przy rozwiązywaniu self-inject). ‘from’ jest rozwiązywane względem provides celu w kontekście uses[].inject, względem provides publikowanych przez encję FeatureRecipe dołączenia w kontekście features. |
arg | inject_delivery | nie | Pojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (lokalny identyfikator — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub niestandardowy klucz specyficzny dla mechanizmu) oraz dokładnie jedno z pól: ‘from’ (klucz provides do rozwiązania) albo ‘value’ (literał tekstowy, opcjonalnie zawierający wyrażenia szablonów Go ewaluowane przy rozwiązywaniu self-inject). ‘from’ jest rozwiązywane względem provides celu w kontekście uses[].inject, względem provides publikowanych przez encję FeatureRecipe dołączenia w kontekście features. |
component_uses_block
Połączenia, które komponent prowadzi do komponentów, od których zależy, z kluczami według gniazda. Każde gniazdo wymienia swoje cele albo nazywa każde połączenie pod aliasem. Połączenie nazwane pod aliasem może zawierać wartości dewelopera dla danego połączenia oraz załączniki wypełniające sloty deklarowane przez gniazdo.
Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
Wartości to string[] or map of object.
Żadne inne klucze nie są dozwolone.
feature_uses_block
Połączenia prowadzone przez załączoną encję Feature, z kluczami według gniazda, które encja Feature deklaruje w swoim usesSchema. Każde gniazdo wymienia swoje cele albo nazywa każde połączenie pod aliasem. Połączenie prowadzone przez encję Feature nie ma własnych załączników: potrzebne mu poświadczenie wypełnia slot, który encja Feature deklaruje we własnym featuresSchema, i jest załączane obok encji Feature.
Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
Wartości to string[] or map of object.
Żadne inne klucze nie są dozwolone.
connection_attachment
Jeden załącznik połączenia: encja Feature wypełniająca slot deklarowany przez gniazdo połączenia, wraz z konfiguracją dewelopera dla niej.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
type | string | tak | URI interfejsu Feature, którego żąda ten załącznik (np. core/referenced-secret:1.0.0). |
description | string | nie | Opcjonalna dokumentacja wyjaśniająca, dlaczego to połączenie zawiera ten załącznik. |
values | object | nie | Konfiguracja encji Feature podana przez dewelopera, walidowana przez deklarację jej schematu. |
Dodatkowe właściwości są niedozwolone.
subsystem
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
description | string | nie | Opcjonalna dokumentacja opisująca cel tego podsystemu i reprezentowane przez niego grupowanie logiczne. |
annotations | mapa string lub object lub null | nie | Adnotacje dewelopera dla tego podsystemu. Wartości są ciągami znaków, obiektami strukturalnymi (mapą podkluczy na wartości, scalaną dla każdego podklucza z odziedziczoną wartością strukturalną) lub null; jawne null dla klucza odziedziczonego z podsystemu nadrzędnego usuwa odziedziczone powiązanie z tego podsystemu (rezygnacja z encji Feature sterowana adnotacjami). Zadeklarowane tu adnotacje są dziedziczone przez zagnieżdżone podsystemy i zawarte w nich komponenty; dla każdego klucza wygrywa poziom bliższy. Kaskadowo trafiają do kubełka .context.annotations.aggregate w każdym pochodnym węźle IR. |
features | mapa object | nie | Przekrojowe funkcje dołączane do wszystkich komponentów w tym podsystemie. Ten sam schemat co funkcje na poziomie komponentu (type, values, uses, inject). Spłaszczane do każdego komponentu przy finalizacji grafu, umieszczane w kolejności wykonania po funkcjach na poziomie komponentu. Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
subsystems | mapa subsystem | nie | Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
components | mapa component_instance | nie | Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
Dodatkowe właściwości są niedozwolone.
component_instance
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
type | string | tak | Żądana abstrakcyjna encja Component w postaci odwołania: jej metadata.name z opcjonalnym :version (np. core/api-server:1.0.0), nigdy ścieżka do pliku. Rozstrzygana według trójpoziomowego modelu rozstrzygania encji (katalogi katalogu obszaru roboczego → pamięć podręczna → rejestr): encję Component utworzoną lokalnie umieszcza się w catalog/ w katalogu głównym obszaru roboczego lub w katalogu wymienionym w workspace.catalog_dirs, a type zapisany jako względna ścieżka do pliku zatrzymuje budowanie jako encja, której nie zawiera żaden katalog. |
active | boolean lub string | nie | Określa, czy ten komponent występuje w skompilowanej topologii. Wartość logiczna albo szablon tekstowy nad .parameters, który musi dać się rozwiązać do wartości logicznej. Gdy rozwiązuje się do false, komponent jest usuwany z topologii wraz z jego krawędziami uses i jego dołączeniami. Sterowanie wartością za pomocą parametru pozwala encji Release włączać i wyłączać obecność komponentu przez wypełnienie tego parametru. Domyślnie true, gdy pole pominięto. Wartość domyślna: true |
description | string | nie | Opcjonalna dokumentacja opisująca rolę tej instancji komponentu w aplikacji. Przenoszona do grafu IR. |
annotations | mapa string lub object lub null | nie | Adnotacje tego komponentu tworzone przez dewelopera. Wartości są ciągami znaków, obiektami strukturalnymi (mapą podkluczy na wartości, scalaną dla każdego podklucza z odziedziczoną wartością strukturalną) lub null; jawne null dla klucza odziedziczonego z nadrzędnego podsystemu usuwa odziedziczone powiązanie z tego komponentu (rezygnacja z encji Feature sterowana adnotacjami). Adnotacje na poziomie encji Component nadpisują odziedziczone adnotacje z poziomu podsystemu dla każdego klucza z osobna; komponenty równorzędne w tym samym podsystemie zachowują niezależnie własne mapy adnotacji. |
values | object | nie | Nieprzejrzyste właściwości kognitywne przekazywane do encji Component, walidowane przez jej schemat. |
uses | component_uses_block | nie | Połączenia, które komponent prowadzi do komponentów, od których zależy, z kluczami według gniazda. Każde gniazdo wymienia swoje cele albo nazywa każde połączenie pod aliasem. Połączenie nazwane pod aliasem może zawierać wartości dewelopera dla danego połączenia oraz załączniki wypełniające sloty deklarowane przez gniazdo. |
inject | inject_block | nie | Samowstrzykiwanie na poziomie komponentu. Wstrzykuje własne wartości komponentu (przez ‘value:’) lub jego własne klucze provides (przez ‘from:’) bezpośrednio do potoku dostarczania (.context.inject). Dozwolone tylko wtedy, gdy encja katalogowa Component deklaruje ‘spec.inject’ z odpowiednimi mechanizmami. Klucz inject kolidujący z kluczem zadeklarowanym w uses[].inject zatrzymuje budowanie jako zduplikowany klucz dostarczania między źródłami inject. |
features | mapa object | nie | Encje Features dołączone do tego komponentu, z kluczami będącymi nazwami instancji, które autor nadaje każdemu dołączeniu. To jedyne miejsce dołączania: operacyjna encja Feature, encja Feature poświadczeń (oznaczona etykietą feature.aggrega.ai/kind: secret) i encja Feature tożsamości są dołączane tutaj, pod tym samym słowem kluczowym i w tym samym kształcie. Różni je to, co dołączenie wytwarza, a nie sposób jego deklarowania. Dołączenie, którego nazwa instancji odpowiada slotowi zadeklarowanemu przez encję Component w featuresSchema, wypełnia ten slot; każda inna nazwa instancji oznacza dołączenie swobodne. Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
Dodatkowe właściwości są niedozwolone.