SchemaLibrary
SchemaLibrary to encja katalogu, która przechowuje definicje JSON Schema 2020-12 wielokrotnego użytku oraz opcjonalne sparametryzowane funkcje pomocnicze. Components i Features, które współdzielą kształty schematów — adresy URL, czasy trwania, typowe struktury sond, powtarzające się limity zasobów — deklarują te kształty raz w bibliotece i odwołują się do nich za pomocą kanonicznych identyfikatorów URI $ref. Encja biblioteki należy do poziomu 3: jest opcjonalna i przeznaczona dla katalogów, które potrzebują ponownego użycia schematów w wielu encjach Component. Katalogi bez powtarzającej się treści schematów obywają się bez żadnej encji SchemaLibrary.
Rola encji SchemaLibrary
Architekci platformy tworzą encje SchemaLibraries, aby scentralizować kształty schematów, które powtarzają się w całym katalogu. Biblioteka nie jest wdrażalnym blokiem konstrukcyjnym; jest przestrzenią nazw definicji. Autorzy encji Component / Feature odwołują się do wpisów biblioteki za pomocą ich kanonicznego URI $ref, typowanego raz i walidowanego wszędzie tam, gdzie odwołanie jest rozwiązywane.
Podział na „bibliotekę” i „konsumenta” jest zamierzony. Encje Components deklarują kontrakt, który wypełnia instancja (jej values, infra i provides, jej sockety, jej miejsca na dane uwierzytelniające). Encje Features kodują dołączane zachowania. Encje SchemaLibraries kodują wyłącznie treść schematów — reguły strukturalne, które wartość musi spełniać. Rozdzielenie tych trzech ról pozwala każdemu rodzajowi encji ewoluować we własnym tempie; autorzy, którzy nie potrzebują współdzielonych definicji schematów, nigdy nie mają do czynienia z encją biblioteki.
Koperta encji
Encja SchemaLibrary zawiera standardową kopertę katalogu. apiVersion: aggrega.ai/v1beta1 i kind: SchemaLibrary oznaczają rodzaj encji; metadata.name to identyfikator w formacie PascalCase; metadata.version stosuje ścisłe wersjonowanie semantyczne. Zawartość biblioteki znajduje się pod spec: spec.schemas jest wymagane (biblioteka musi deklarować co najmniej jeden wpis), a spec.templates jest opcjonalne (występuje tylko wtedy, gdy biblioteka używa sparametryzowanych elementów pomocniczych).
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Tworzenie wpisów schematu
Wpisy schematu tworzy się w jednej z trzech form. Forma kompaktowa jest domyślną powierzchnią dla krótkich, typowych kształtów — type, pattern, enum, min, max i podobnych jednowierszowych ograniczeń. JSON Schema 2020-12 w YAML jest równorzędną opcją tworzenia wpisów, które wymagają pełnej powierzchni JSON Schema (słowa kluczowe kompozycji, kształt warunkowy, złożone $defs). Łączenie obu form w jednym wpisie jest obsługiwane dzięki rozdzielaniu według kształtu treści w każdym węźle, które wykonuje kompilator formy kompaktowej; furtka $jsonschema: osadza pełną treść JSON Schema w dowolnym węźle, gdy forma kompaktowa nie może wyrazić zamiaru.
format we wpisie sprawdza to samo, co w dowolnym schemacie: wskazuje jeden z formatów email, uri, hostname, ipv4, ipv6, uuid, date-time i date, a wartość, którą konsument podaje dla pola, jest odrzucana, chyba że ma ten format — zob. vocabulary/compact-form-authoring.md. Wpis wskazujący dowolny inny format — łącznie z password — jest odrzucany podczas ładowania biblioteki, więc aggrega validate dla całego katalogu odrzuca go niezależnie od tego, czy cokolwiek już się do niego odwołuje, podając bibliotekę, wpis i nazwę oraz wymieniając obsługiwane formaty, a kompilacja lub pobranie, w którym encja Release sięga do tej biblioteki, zostaje na nim zatrzymane. Wpis odwołujący się do innej biblioteki jest oceniany tam, gdzie konsumuje go filar encji Component lub Feature. Pole przenoszące dane poufne deklaruje sensitive: true zamiast formatu.
Szablony i $instantiate:
Biblioteki o znacznej powtarzalnej strukturze deklarują sparametryzowane funkcje pomocnicze w spec.templates. Szablon zawiera mapę $params: (deklaracje nazwanych, typowanych parametrów) oraz treść (w formie kompaktowej lub jako zawartość JSON Schema), która odwołuje się do parametrów jako tokenów skalarnych $<paramName>. Wpisy schematów tworzą instancje szablonów za pomocą powiązań $instantiate: + $args:; silnik podstawiania zastępuje symbole zastępcze parametrów dosłownymi wartościami skalarnymi i generuje treść rozwiązanego wpisu.
spec: schemas: LivenessProbe: $instantiate: ProbeTemplate $args: port: 8080 path: /healthz ReadinessProbe: $instantiate: ProbeTemplate $args: port: 8081 path: /ready templates: ProbeTemplate: $params: port: type: integer path: type: string type: object properties: port: type: integer const: $port path: type: string const: $pathPodstawianie obejmuje wyłącznie dosłowne wartości skalarne. Silnik podstawiania nie interpretuje składni szablonów Go, nie oblicza warunków ani nie wykonuje pętli. Autorzy potrzebujący bardziej ekspresyjnych funkcji pomocniczych tworzą encje Components lub Features, które korzystają z wpisów biblioteki z własnymi wariantami.
Konwencje nazewnictwa
Nazwy bibliotek, klucze wpisów schematów i nazwy szablonów stosują PascalCase. JSON Schema koperty encji wymusza tę konwencję w trzech miejscach za pomocą ograniczeń wzorca:
metadata.namepasuje do^[A-Z][A-Za-z0-9]*$.- Klucze mapy
spec.schemaspasują do tego samego wzorca za pomocąpropertyNames. - Klucze mapy
spec.templatespasują do tego samego wzorca za pomocąpropertyNames.
Encja SchemaLibrary z kluczem niezgodnym z PascalCase w spec.schemas lub spec.templates nie przechodzi walidacji koperty podczas ładowania przestrzeni roboczej. Wymuszanie na poziomie koperty jest kluczowe: klucze wpisów schematów występują w kanonicznych URI $id (#/schemas/<name>), a nazwy szablonów odwołują się do kanonicznych URI w momencie instancjacji. Wychwycenie kluczy niezgodnych z PascalCase podczas ładowania zapobiega ich rozprzestrzenianiu się w ekosystemie katalogów.
Nazwy parametrów w mapie $params: szablonu są lokalne dla szablonu — nie występują w kanonicznych URI $id i nie podlegają ograniczeniom wzorca na poziomie koperty. Autorzy stosują dowolną konwencję nazewnictwa pasującą do parametrów szablonu; typowe są port, path, intervalSec i podobne nazwy parametrów pisane małymi literami.
Jednolite nazewnictwo na poziomie bibliotek, schematów i szablonów sprawia, że identyfikatory odwołań są czytelne: WebPrimitives#/schemas/URL można zrozumieć na pierwszy rzut oka.
Semantykę rozwiązywania odwołań $ref: między dokumentami — sposób rozwiązywania $ref: poza granicami encji SchemaLibrary, różnicę w składni required: dla konsumentów zawierających $ref:, rozwijanie łańcuchów biblioteka–biblioteka oraz zawężanie biblioteki przez konsumenta — opisano w vocabulary/cross-document-ref.md.
Odwoływanie się do wpisów biblioteki
Autorzy encji Component / Feature odwołują się do wpisu biblioteki przez jego tożsamość — formę samej nazwy <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"Nazwa biblioteki jest rozwiązywana względem rozwiązanego katalogu; fragment #/schemas/<name> wybiera wpis. Odwołanie nie zawiera hosta rejestru; autor może zadeklarować opcjonalną dolną granicę wersji jako <Library>:<version>#/schemas/<name> (separatorem wersji jest :, tak jak w mapowaniach recipe/feature i przypięciach w pliku blokady), ale rozwiązana wersja pochodzi z pliku blokady danej encji Release, który przypina każdą używaną bibliotekę według nazwy, wersji i skrótu zawartości. Odwołanie zawierające host rejestru — forma oci://<host>/… — jest odrzucane podczas kompilacji z komunikatem diagnostycznym kierującym autora do formy tożsamości, dzięki czemu fizyczna lokalizacja rejestru nigdy nie trafia do kodu źródłowego. Skąd serwowane są bajty biblioteki (z lokalnego katalogu, z pamięci podręcznej treści lub ze zdalnego rejestru), to sprawa resolvera, ustalana w momencie rozwiązywania; przeniesienie rejestru jest zmianą konfiguracji resolvera, a nie zmianą kodu źródłowego.
Zabronione słowa kluczowe JSON Schema
Słowa kluczowe JSON Schema 2020-12 $dynamicAnchor i $dynamicRef są zabronione we wpisach encji SchemaLibrary. Parser encji SchemaLibrary skanuje zarówno wpisy schematów, jak i treści szablonów w czasie ładowania obszaru roboczego; linter publikacji stosuje nadmiarowe zabezpieczenie w czasie publikacji; silnik instancjonowania ponownie skanuje rozwiązaną treść po podstawieniu parametrów, więc szablon, który przemyca zabronione słowa kluczowe przez wartości parametrów, i tak kończy się błędem. Trzy skany razem zamykają ścieżkę wprowadzenia statycznego (literalne $dynamicAnchor we wpisie schematu lub treści szablonu), ścieżkę wprowadzenia parametrycznego (wartość $args: zawierająca $dynamicRef) oraz ścieżkę obejścia przez narzędzia spoza głównego obiegu (zabezpieczenie w czasie publikacji wychwytuje wszystko, co ominęło parser).
Gdy odrzucenie nastąpi, błąd wskazuje problematyczne słowo kluczowe i ścieżkę pliku. Autorzy widzą błąd już w czasie tworzenia, a nie przy pierwszym instancjonowaniu; treści szablonów nie są wyłączone ze skanowania podczas ładowania.
Semantyka dynamicznych odwołań wiąże się z ewaluacją w czasie wykonania w sposób, który narusza kontrakt determinizmu kompilatora w czasie kompilacji. Autorzy, którzy potrzebują zachowania dynamicznych odwołań, przebudowują schemat tak, aby używał statycznego rozwiązywania $ref; tej kontroli nie można wyłączyć.
Umiejscowienie w poziomach
SchemaLibrary to poziom 3 w modelu dokumentacji poziomów encji — opcjonalny, przeznaczony dla katalogów, które potrzebują ponownego użycia schematów między encjami Component. Katalogi bez powtarzającej się treści schematów obywają się bez żadnej encji SchemaLibrary; oznaczenie poziomu sygnalizuje „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji po dokumentacji, a nie możliwości. Kompilator traktuje SchemaLibrary jednakowo z pozostałymi rodzajami encji katalogu: ta sama walidacja koperty podczas ładowania przestrzeni roboczej, ten sam potok JSON Schema 2020-12 dla treści poszczególnych wpisów, ten sam potok publikowania OCI w czasie wydania.
W obrębie poziomu 3 sam mechanizm parametrycznych pomocników spec.templates jest opcjonalny. Biblioteki o znacznej powtarzającej się strukturze (szablon sondy sparametryzowany portem i ścieżką; szablon CORS sparametryzowany dozwolonymi źródłami; szablon TLS sparametryzowany ścieżkami certyfikatu i klucza) zyskują na ponownym użyciu templates; biblioteki o zróżnicowanych, jednorazowych wpisach całkowicie pomijają blok szablonów i definiują każdy wpis bezpośrednio w spec.schemas.