Schemat Aggrega Catalog (Feature)
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/feature-v1beta1.schema.json
Modułowa funkcja operacyjna, która dynamicznie wiąże się z komponentami.
Wskazówki dotyczące tworzenia encji Feature zawiera dokumentacja tworzenia encji Feature; ta strona dokumentuje schemat strukturalny, który opisuje tamta dokumentacja.
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 “Feature” | tak | Stała: "Feature" |
metadata | object | tak | |
spec | object | tak | Kontrakt walidacji, wskazywania celu i interoperacyjności dla encji Feature z katalogu: filary o dowolnym kształcie (values, infra, provides) definiowane przez schema, filary o stałym kształcie (gniazda zależności usesSchema, sloty dołączania featuresSchema), wskazywanie komponentów docelowych (appliesTo i appliesToAnyOf) oraz mechanizmy kontroli interoperacyjności. |
Dodatkowe właściwości są niedozwolone.
feature.metadata
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Co najmniej 1 znak. |
version | string | tak | Wersja funkcji w ścisłym formacie Semantic Versioning (np. 1.0.0). 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 | Czym jest ta encja i do czego służy, napisane dla kogoś, kto decyduje, czy jej użyć. Należy zacząć od zdania nazywającego rzecz, a następnie dodać to, czego czytelnik potrzebuje, aby ją wybrać i poprawnie użyć — czego oczekuje od encji Release, która ją wdraża, oraz wszystko, co zaskakuje w jej zachowaniu. Zwykle wystarcza krótki akapit. |
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 | object | nie | Etykiety typowania kaczego dla encji Feature. Zarezerwowana etykieta ‘feature.aggrega.ai/kind’ o wartości ‘secret’ oznacza tę encję jako Feature z poświadczeniami dla autora i dla narzędzi, które ją prezentują. Encję Feature z poświadczeniami i zwykłą encję Feature dołącza się w ten sam sposób, w tym samym miejscu dołączania; o tym, co daje dołączenie, decyduje FeatureRecipe, na który Manifest mapuje jego typ, a nie etykieta. |
annotations | mapa string | nie | Niezmienne, wewnętrzne cechy funkcji definiowane przez architekta platformy w domenie 2. Przekazywane w dół do zasobnika .context.annotations.catalog. |
Dodatkowe właściwości są niedozwolone.
feature.metadata.maintainers[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | |
email | string | nie | |
url | string | nie |
Dodatkowe właściwości są niedozwolone.
feature.metadata.labels
Etykiety typowania kaczego dla encji Feature. Zarezerwowana etykieta ‘feature.aggrega.ai/kind’ o wartości ‘secret’ oznacza tę encję jako Feature z poświadczeniami dla autora i dla narzędzi, które ją prezentują. Encję Feature z poświadczeniami i zwykłą encję Feature dołącza się w ten sam sposób, w tym samym miejscu dołączania; o tym, co daje dołączenie, decyduje FeatureRecipe, na który Manifest mapuje jego typ, a nie etykieta.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | nie | Etykieta rodzaju encji Feature. Wartość ‘secret’ oznacza tę encję jako Feature z poświadczeniami. Dozwolone wartości: "secret" |
feature.spec
Kontrakt walidacji, wskazywania celu i interoperacyjności dla encji Feature z katalogu: filary o dowolnym kształcie (values, infra, provides) definiowane przez schema, filary o stałym kształcie (gniazda zależności usesSchema, sloty dołączania featuresSchema), wskazywanie komponentów docelowych (appliesTo i appliesToAnyOf) oraz mechanizmy kontroli interoperacyjności.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
extends | string | nie | Odwołanie do bazowej encji Feature, po której dziedziczy ta encja Feature. Wskazuje bazę przez jej metadata.name, a nie przez współrzędną rejestru, pod którą encja Feature jest publikowana, i przyjmuje te same trzy formy wersji co każde odwołanie do katalogu: samą nazwę (core/queue) dla najwyższego dostępnego wydania, wersję dokładną (core/queue:1.0.0) lub zakres z daszkiem (core/queue:^1.0.0). Dziedziczone są nie tylko metadane: metadata.labels i metadata.annotations bazy, jej selektory appliesTo i appliesToAnyOf, jej blok interoperability, jej usesSchema i jej featuresSchema są scalane w dół, a jej deklaracje JSON Schema 2020-12 w schema są scalane automatycznie. Przy wspólnym kluczu wygrywa wartość potomka, a pola tożsamości nigdy nie są dziedziczone. |
featuresSchema | mapa object | nie | Deklaratywne definicje slotów dołączania: nazwane punkty wiązania, w których ta encja Feature oczekuje dołączenia kolejnej encji Feature. Slot ogranicza, które wypełnienie może go związać (selector) i jak może zostać dostarczony materiał wypełnienia (inject); kontraktem values i infra wypełnienia zarządza jego własna encja Feature. Zadeklarowanie slotu nigdy nie zamyka bloku dołączeń — autor może dołączyć encję Feature pod nazwą, której żaden slot nie deklaruje. Slot jest punktem wiązania, a nie gniazdem zależności: odrębną powierzchnię topologii deklaruje usesSchema. |
appliesTo | string | nie | Ciąg selektora etykiet w stylu Kubernetes dopasowujący encje Components. Wszystkie wymagania rozdzielone przecinkami muszą być spełnione (AND). Obsługiwane formy: key=value, key!=value, key in (v1, v2), key notin (v1, v2), sam klucz (etykieta obecna), !key (etykieta nieobecna). Przykład: „tier in (critical, production), !legacy”. Pusty lub nieobecny selektor nie deklaruje żadnego ograniczenia. Selektor jest odczytywany według tych form przy każdej ewaluacji dołączenia tej encji Feature, a wymaganie spoza nich zatrzymuje kompilację z jego wskazaniem: puste wymaganie (przecinek na początku, na końcu lub podwojony) albo klucz zawierający białe znaki lub dowolny ze znaków = ! ( ) i przecinek — dlatego „!tier=frontend” jest odrzucane, a wartość wyklucza się przez tier!=frontend. Wartością jest tekst po operatorze, niezależnie od zawartych w nim znaków. Wzorzec tego pola odrzuca jedynie kilka błędnych kształtów, zanim zostanie ewaluowane jakiekolwiek dołączenie. Wzorzec: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string lub mapa string[] | nie | Lista selektorów; encja Feature ma zastosowanie, jeśli DOWOLNY element pasuje (logika OR). Każdy element jest albo ciągiem selektora etykiet (ta sama gramatyka co appliesTo; wymagania wewnątrz ciągu łączy AND), albo płaską mapą klucz-wartość, w której każda para musi pasować (tylko równość). |
interoperability | object | nie | Zaawansowane mechanizmy kontroli bezpieczeństwa operacyjnego i interoperacyjności. |
usesSchema | mapa object | nie | Gniazda zależności deklarowane przez tę encję, kluczowane nazwą gniazda; każde połączenie poprowadzone przez gniazdo jest sprawdzane względem deklaracji tego gniazda — jego selektora i dozwolonych mechanizmów inject. Klucze: jedna lub więcej liter, cyfr, podkreśleń lub łączników. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
schema | object | nie | Treść JSON Schema 2020-12 obejmująca filary o dowolnym kształcie: values (domena programisty — parametry kształtu aplikacji, które programista konfiguruje dla każdego dołączenia Feature w encji Aggregate); infra (domena operatora — parametry fizycznego wymiarowania dostarczane przez encję Release); oraz provides (klucze kontekstu w dół, które ten Feature udostępnia konsumentom przez potok topologii). Akceptuje trzy tryby tworzenia, rozróżniane według kształtu treści: (1) treść osadzona (mapa YAML zawierająca formę zwartą, JSON Schema w YAML lub ich połączenie); (2) zastąpienie plikiem przez {$import: |
assertions | mapa string | nie | Walidacja międzypolowa w czasie kompilacji. Każdy wpis jest nazwaną asercją: kluczem jest stabilny identyfikator reguły pokazywany w komunikatach o błędach; wartością jest ciąg szablonu Go z semantyką zatrzymania {{ fail "message" }}. Wiele nazwanych asercji encji jest ewaluowanych dla każdej instancji w kolejności zadeklarowanej przez autora; pierwsza niespełniona asercja zatrzymuje kompilację. Asercje encji Feature są ewaluowane po rozwiązaniu i analizie statycznej, przed renderowaniem, i wyrażają niezmienniki architektoniczne kontraktu. Kontekst szablonu: .values / .infra / .uses / .features / .metadata. Ewaluator używa missingkey=error: odwołania do niezdefiniowanych kluczy zatrzymują kompilację z diagnostyką braku klucza. Ponieważ samo odwołanie zatrzymuje kompilację, zanim zadziała jakakolwiek wartość zastępcza, zwykłe default nie zapewnia na tej powierzchni wartości zastępczej dla pola opcjonalnego — należy zabezpieczyć odwołanie przez hasKey lub użyć funkcji pomocniczej optional, która bezpośrednio sprawdza obecność. Odczyt klucza przez index również jej nie zapewnia: index zatrzymuje kompilację przy kluczu, którego mapa nie zawiera, wskazując ten klucz. |
Dodatkowe właściwości są niedozwolone.
feature.spec.interoperability
Zaawansowane mechanizmy kontroli bezpieczeństwa operacyjnego i interoperacyjności.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
conflictsWith | string[] | nie | Nazwy encji Features, z którymi ta encja Feature nie może trafić do jednego komponentu, każda zapisana tak, jak typ dołączenia nazywa encję Feature. Kompilacja zatrzymuje się przed renderowaniem, gdy jeden komponent zawiera tę encję Feature i encję Feature tu wymienioną — niezależnie od tego, czy każda została dołączona do komponentu, do zawierającego go podsystemu lub granicy, do wpisu komponentu w encji Release, czy przez rozwinięcie sterowane adnotacjami. Wystarczy jedna deklaracja: zatrzymanie nie wymaga, aby druga encja Feature wymieniała tę. Nazwy są porównywane po usunięciu wersji, więc wpis pasuje do każdej wersji wskazanej encji Feature. Dwie encje Features dołączone do sąsiednich granic, które nie mają wspólnego komponentu, nigdy się nie spotykają i nie powodują zatrzymania. |
Dodatkowe właściwości są niedozwolone.