Schemat Aggrega Catalog (Component)
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/component-v1beta1.schema.json
Abstrakcyjna definicja atomowego elementu konstrukcyjnego.
Opisowe wskazówki dotyczące tworzenia encji Component zawiera dokumentacja tworzenia encji Component; ta strona dokumentuje schemat strukturalny, który opisuje ta 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 “Component” | tak | Stała: "Component" |
metadata | object | tak | |
spec | object | tak | Definicje walidacji i schematu regulujące nieprzezroczysty ładunek wartości dewelopera. |
Dodatkowe właściwości są niedozwolone.
component.metadata
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Co najmniej 1 znak. |
version | string | tak | Wersja interfejsu 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 | tak | Etykiety w stylu duck typing służące do deklarowania cech. Muszą zawierać zarezerwowany klucz ‘component.aggrega.ai/type’. |
annotations | mapa string | nie | Niezmienne, wewnętrzne cechy komponentu tworzone przez architekta platformy w domenie 2. Przechodzą kaskadowo do kubełka .context.annotations.catalog. |
Dodatkowe właściwości są niedozwolone.
component.metadata.maintainers[]
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | |
email | string | nie | |
url | string | nie |
Dodatkowe właściwości są niedozwolone.
component.metadata.labels
Etykiety w stylu duck typing służące do deklarowania cech. Muszą zawierać zarezerwowany klucz ‘component.aggrega.ai/type’.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | tak | Zarezerwowana oś określająca, jakiego rodzaju rzeczą jest ten komponent. Aggrega definiuje ten klucz i akceptowane przez niego wartości, więc zbiór jest zamknięty; aby klasyfikować komponenty według własnej osi, należy dodać własny klucz etykiety obok tego. Dozwolone wartości: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Definicje walidacji i schematu regulujące nieprzezroczysty ładunek wartości dewelopera.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
extends | string | nie | URI bazowej encji Component, którą ta encja Component rozszerza. Rozszerzanie składa strukturę: etykiety i adnotacje metadanych bazy, jej gniazda dołączeń (featuresSchema), jej lista dozwolonych mechanizmów self-inject (inject) i jej gniazda topologii (usesSchema) są dziedziczone, a ta encja Component może je uzupełniać lub zastępować odziedziczony wpis klucz po kluczu. Filary danych bazy NIE są składane — blok schema bazy jest dziedziczony dokładnie w takiej postaci, w jakiej utworzyła go baza, więc rozszerzająca encja Component zapisuje schema: inherited i nie tworzy własnej treści filarów. |
featuresSchema | mapa object | nie | Deklaratywne definicje gniazd dołączeń: nazwane punkty wiązania, w których ta encja oczekuje dołączenia encji Feature. Gniazdo ogranicza, jakie wypełnienie może się z nim związać (selector) i jak może być dostarczany materiał wypełnienia (inject); własna encja Feature wypełnienia jest właścicielem jego wartości i kontraktu infra. Zadeklarowanie gniazda nigdy nie zamyka bloku dołączeń — autor może dołączyć encję Feature pod nazwą, której nie deklaruje żadne gniazdo, dzięki czemu jedna encja służy zarówno jako dołączenie wypełniające gniazdo, jak i jako poświadczenie współdzielone w szerszym zakresie. Gniazdo jest punktem wiązania, a nie gniazdem zależności: odrębną powierzchnię topologii deklaruje usesSchema. |
inject | string[] | nie | Dozwolone mechanizmy dostarczania self-inject (np. [‘env’, ‘file’, ‘arg’]). Gdy pole jest obecne, deweloperzy mogą używać bloku inject: na poziomie komponentu w encji Aggregate, aby wstrzykiwać własne values lub klucze provides bezpośrednio do potoku dostarczania. Jeśli pole zostanie pominięte, self-inject na poziomie komponentu jest zabroniony (wzorzec Black-Box — encja Recipe obsługuje całe wewnętrzne okablowanie). Semantyka taka sama jak w usesSchema[].inject, ale dotyczy własnych values komponentu, a nie topologii między komponentami. Można wymienić dowolną nazwę mechanizmu z wyjątkiem all, której żaden blok inject nie może użyć. |
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, dozwolonych mechanizmów inject i kontraktów dla poszczególnych połączeń. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$. |
schema | any | 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żdej instancji Component w encji Aggregate); infra (domena operatora — fizyczne parametry wymiarowania dostarczane przez encję Release); oraz provides (klucze kontekstu w dół strumienia, które ta encja Component udostępnia konsumentom przez potok topologii). Akceptuje cztery tryby tworzenia, rozróżniane według kształtu treści: (1) treść inline (mapa YAML w formie zwartej, YAML JSON Schema lub mieszana); (2) zastąpienie plikiem przez {$import: |
assertions | mapa string | nie | Walidacja międzypolowa w czasie budowania. Każdy wpis jest nazwaną asercją: klucz jest stabilnym identyfikatorem reguły wyświetlanym w komunikatach o błędach; wartość jest ciągiem szablonu Go z semantyką zatrzymania {{ fail "message" }}. Wiele nazwanych asercji na encję jest ewaluowanych dla każdej instancji w kolejności zadeklarowanej przez autora; pierwsza niespełniona asercja zatrzymuje budowanie. Asercje encji Component są ewaluowane po rozwiązaniu i analizie statycznej, przed renderowaniem, i wyrażają niezmienniki architektoniczne kontraktu, które obowiązują niezależnie od tego, która encja Recipe się wiąże. Kontekst szablonu: .values / .infra / .uses / .features / .metadata. Ewaluator używa missingkey=error: odwołania do niezdefiniowanych kluczy zatrzymują budowanie z diagnostyką no-such-key. Ponieważ samo odwołanie zatrzymuje budowanie, zanim może 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ć pomocnika optional, który bezpośrednio sprawdza obecność. Odczyt klucza przez index również jej nie zapewnia: index zatrzymuje budowanie na kluczu, którego mapa nie zawiera, podając ten klucz. Dziedziczenie jest addytywne: encja Component deklarująca extends jest ewaluowana względem asercji, które dziedziczy, oraz własnych, przy czym odziedziczone reguły są pierwsze, a łańcuch o dowolnej głębokości akumuluje się od korzenia łańcucha w dół — więc gdy niespełniona byłaby więcej niż jedna reguła, zgłaszana jest ta zadeklarowana najwyżej w łańcuchu. Ponowne użycie odziedziczonej nazwy do zadeklarowania innej reguły jest odrzucane, gdy łańcuch extends jest rozwiązywany względem katalogu, z podaniem obu encji Components i wspólnej nazwy — ujawnia się to więc, gdy bazowa encja Component jest obecna, a nie na podstawie samego dokumentu rozszerzającego; rozszerzająca encja Component dodaje reguły i nigdy żadnej nie zastępuje. Powtórzenie odziedziczonej reguły bajt w bajt pod jej własną nazwą jest akceptowane jako operacja pusta, którą w istocie jest. Nic nie sprawdza, czy dwie reguły mogą być spełnione jednocześnie: wzajemnie niespełnialna para jest błędem autorskim, który ujawnia się jako zwykłe niespełnienie asercji, gdy instancja wyzwoli tę, która zadziała pierwsza, a nigdy jako wcześniejsze ostrzeżenie. |
Dodatkowe właściwości są niedozwolone.
Definicje
extending-component-must-declare-schema-inherited
Ma zastosowanie, gdy spec.extends jest obecne. Rozszerzająca encja Component otrzymuje values / infra / provides swojej bazy dokładnie w takiej postaci, w jakiej baza je napisała, dlatego deklaruje spec.schema: inherited i nie zawiera własnej treści filarów. Oba pozostałe warianty są błędami i są to różne pomyłki: całkowite pominięcie spec.schema, przez które czytelnik nie odróżniłby odziedziczonego bloku filarów od zapomnianego; oraz napisanie treści filarów pod spec.schema, co oznaczałoby żądanie drugiego, rozbieżnego kontraktu dla encji Component, której kontraktem jest kontrakt jej bazy.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
schema | const “inherited” | tak | Znacznik dziedziczenia i jedyna wartość, jaką przyjmuje spec.schema w encji Component deklarującej extends. Wskazuje, skąd pochodzą filary; sama treść filarów należy do bazowej encji Component. Stała: "inherited" |
non-extending-component-authors-its-own-schema
Ma zastosowanie, gdy spec.extends jest nieobecne. Encja Component, która nie rozszerza żadnej bazy, zawiera własną treść values / infra / provides pod spec.schema, więc to pole zawiera napisaną treść, a nie znacznik inherited: znacznik oznacza, że filary pochodzą z bazy, a ta encja Component jej nie ma.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
schema | object | nie | Napisana treść filarów — mapa w dowolnym z trzech trybów tworzenia treści opisanych w spec.schema. |