Zakres walidacji
Aggrega waliduje tworzoną treść w czterech odrębnych warstwach schematów. Każda warstwa obejmuje inny zakres, działa w innym punkcie potoku kompilacji i zgłasza błędy o innym kształcie. Autor, który napotka błąd walidacji, zyskuje na wiedzy o tym, która warstwa odrzuciła dane wejściowe — to samo pole może podlegać więcej niż jednej warstwie, a warstwa, która zadziałała, określa, co i gdzie należy poprawić.
Ta strona opisuje cztery warstwy, ich miejsce w potoku, konwencję kształtu błędów, której przestrzega każda warstwa, oraz sposób, w jaki warstwy współdziałają, gdy do tego samego pola stosuje się więcej niż jedna z nich.
Cztery warstwy
Warstwa 1 — koperta JSON Schema
Zakres. Struktura każdego pliku YAML katalogu: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, blok najwyższego poziomu spec: oraz wymagane pola poszczególnych encji deklarowane przez schemat. Każdy rodzaj encji (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) ma własny JSON Schema, opisany w dokumentacji schematów. Workload również ma tam swój schemat i jest jedynym rodzajem w tym zbiorze, który autor zapisuje wewnątrz innej encji — w bloku workload: encji Recipe lub FeatureRecipe albo we wpisie WorkloadLibrary — a nie jako osobny plik katalogu; ta sama kontrola koperty obowiązuje go wszędzie, gdzie jest zapisany, a aggrega validate przyjmuje plik Workload bezpośrednio jako cel z pojedynczą encją.
Kiedy działa walidacja. Podczas rozwiązywania (resolver / ładowanie), dla każdego pliku osobno. Każdy dokument jest sprawdzany przy ładowaniu względem JSON Schema swojego rodzaju; klucz spoza pól zadeklarowanych przez schemat zostaje tam odrzucony, zanim zostanie uruchomiona jakakolwiek dalsza walidacja.
Kształt błędu. Niezgodność ze schematem jest zgłaszana jako błąd koperty dokumentu. Jego nagłówek zawiera kategorię dokumentu, w którym leży błąd — [CATALOG_ERROR E0215] dla encji katalogu, [DEVELOPER_ERROR E0215] dla Aggregate, [OPS_ERROR E0215] dla Release — a komunikat podaje rodzaj, plik, wiersz i kolumnę, ścieżkę pola oraz naruszone ograniczenie:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schemaPominięcia wymaganych pól i niezgodności typów pojawiają się w tym samym kształcie — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Warstwa 2 — schematy filarów (schema: / featuresSchema / usesSchema)
Zakres. Filary danych, które niesie encja — values, infra, parameters, a także blok dołączeń features:, którego sloty deklaruje featuresSchema, oraz blok uses: regulowany przez usesSchema. Encje domeny 2 (Component, Feature) osadzają deklaracje JSON Schema 2020-12 w swojej kopercie YAML (spec.schema inline — w formie zwartej lub pełnej — albo $ref: do współdzielonego wpisu SchemaLibrary); encje domeny 3 (Recipe, FeatureRecipe) korzystają z rozwiązanych schematów podczas własnego przebiegu walidacji.
Kiedy działa walidacja. Podczas rozwiązywania, po pomyślnym sprawdzeniu koperty JSON Schema. Kompilator składa napisany przez autora schema: encji z automatycznie generowanymi bazami wyprowadzonymi z deklaracji usesSchema i featuresSchema; złożony schemat waliduje dostarczone przez dewelopera bloki values: / infra: / features: / uses: w każdej instancji komponentu w encji Aggregate.
Postać błędu. Naruszenia ograniczeń pojawiają się jako komunikaty wskazujące encję, ścieżkę wewnątrz filaru i regułę, która odrzuciła wartość — na przykład gdy deweloper ustawia port na 80 wbrew regule schematu wymagającej >=1024.
Ponownie zadeklarowany wpis usesSchema lub featuresSchema nie powoduje błędu składania. Te dwie powierzchnie nakładają się według nazwy: wpis potomny całkowicie zastępuje wpis bazowy, schemat i selektor razem, więc nie ma konfliktu między wpisem bazowym a potomnym, który trzeba by zgłosić.
Warstwa 3 — zdolność Provider do trybu syntetyzowanego
Zakres. Regulowany przez bramkę zdolności powiązanego providera do trybu syntetyzowanego:
- Obsługa trybu syntetyzowanego (
workload:) zależy od zdolności powiązanego providera, a nie od obecnościworkloadSchema: encja Recipe zworkload:powiązana z providerem, który nie potrafi syntetyzować, jest tu odrzucana. Katalog biblioteki standardowej zgodnie z konwencją deklarujeworkloadSchemaw providerach zdolnych do syntezy — wspec.provider.workloadSchemaencji Plugin renderującej Provider — jako udokumentowany kontrakt translacji. Sama treśćworkloadSchemajest kompilowana do JSON Schema 2020-12 podczas ładowania encji Plugin; jest to strukturalna bramka akceptacji, która odrzuca błędny schemat przy ładowaniu, a nie przy renderowaniu.
Kiedy działa walidacja. Podczas renderowania bazowego, po rozwiązaniu własnego valuesMapping encji Recipe. Warstwa 3 uzależnia dyspozycję trybu syntetyzowanego od zdolności providera.
Postać błędu. Odmowa z powodu braku zdolności jest przypisywana domenie tworzenia katalogu, więc raport zaczyna się nagłówkiem w nawiasach kwadratowych zawierającym tę kategorię i instancję, której dotyczy błąd. Komunikat zaczyna się stałym zdaniem opisującym warunek, a następnie wskazuje węzeł, providera i rodzaje, które ten provider obsługuje:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesizedNagłówek [CATALOG_ERROR] sygnalizuje, że winna jest encja katalogu, a nie encja Aggregate dewelopera. W terminalu nagłówek zawiera też krótki kod warunku — w tym przypadku E0265, który wyjaśnia tabela wszystkich warunków — a komunikat przechodzi do osobnego wciętego wiersza; powyższa forma jednowierszowa trafia do logu. Zdanie otwierające jest stałe dla danego warunku, więc to na nim należy opierać dopasowanie przy pracy z tekstem; wszystko, co następuje po nim, zależy od winnego węzła.
Pokrewne zabezpieczenie chroni samą dyspozycję do providera: gdy ten sam cel obsługuje więcej niż jedna encja Plugin renderująca Provider, przestrzeń robocza rozstrzyga niejednoznaczność za pomocą powiązania providera w .aggrega-config.yaml, wybranego przy aggrega pull i zapisanego w pliku blokady. Gdy nie ma powiązania i istnieje dokładnie jedna kandydująca encja Plugin, używany jest ten kandydat; gdy nie ma powiązania, a kandydatów jest więcej, kompilacja zatrzymuje się z wyraźnym błędem, wymieniając kandydujące pluginy. Niejednoznaczność jest rozstrzygana dla każdej przestrzeni roboczej w miejscu użycia, a nie przez regułę unikalności obowiązującą w całym katalogu.
Walidacja treści Workload dla poszczególnych providerów. Pole
spec.provider.workloadSchemaencji Plugin renderującej providera dokumentuje, jak provider tłumaczy Workload, i oznacza providera jako zdolnego do jego syntezy; niczego nie waliduje. Każda treść Workload jest walidowana względem schematu Workload platformy, niezależnie od providera.
Warstwa 4 — walidacja wartości powiązań adnotacji
Zakres. Wartości adnotacji zapisane na granicach Release / komponentach granicznych lub podsystemach Aggregate / instancjach komponentów, gdy powiązanie Manifest pod mappings.features.annotations.<key> deklaruje routing przez listy ścieżek kropkowych maps.infra i/lub maps.values. Każda zadeklarowana ścieżka prowadzi przez spec.schema.<pillar> docelowej encji Feature do właściwości liścia; wkład wartości adnotacji w tym liściu jest walidowany względem typu zadeklarowanego w schemacie Feature. Walidacja przebiega przez własną deklarację JSON Schema 2020-12 encji Feature — powiązania deklarują tylko routing, a nie fragmenty walidacji.
Kiedy działa walidacja. W podfazie rozwijania adnotacji podczas rozwiązywania, po walidacji celów powiązań Manifest (kontroli przy ładowaniu katalogu, potwierdzającej, że każda zadeklarowana ścieżka istnieje w schemacie wskazanej encji Feature) i równolegle z walidacją schematów warstwy 2 dla jawnych dołączeń. Dla każdej efektywnej adnotacji komponentu: wartość jest parsowana jako skalar, mapa strukturalna lub jawne null; routing według podkluczy przebiega przez pogrupowaną według filarów deklarację maps powiązania z wymuszaniem zgodności strony i filaru (strona Aggregate uruchamia maps.values; strona Release uruchamia maps.infra); wartość czasu wykonania w każdym liściu jest walidowana względem typu zadeklarowanego w schemacie Feature w filarze docelowym. Błędy wielu podkluczy są zbierane i zgłaszane wszystkie przed zatrzymaniem.
Postać błędu. Błędy walidacji schematu w tej warstwie mają postać z warstwy 2 — encja, ścieżka (klucz adnotacji plus trasa podklucza), szczegóły ograniczenia. Naruszenia podziału strona–filar i błędy niejednoznacznego routingu są przypisywane dokumentowi, w którym zapisano wartość adnotacji, więc błąd pochodzący z encji Aggregate otwiera nagłówek [DEVELOPER_ERROR], a pochodzący z encji Release — nagłówek [OPS_ERROR]; oba wskazują klucz adnotacji, filar docelowy, stronę autorską i lokalizację w źródle.
Jedna konwencja formatowania błędów we wszystkich warstwach
Cztery warstwy łączy jedna obserwowalna konwencja: każdy błąd walidacji przypisywalny do Aggrega ma kształt „ścieżka plus uzasadnienie”, który wskazuje błędne pole i ograniczenie, które je odrzuciło.
- Błędy warstwy 1 (koperta) i warstwy 2 (schematy filarów) zaczynają się od tego samego nagłówka w nawiasach kwadratowych — kategorii dokumentu, w którym leży błąd, i krótkiego kodu warunku, np.
[CATALOG_ERROR E0215]dla niezgodności koperty w encji katalogu i[DEVELOPER_ERROR E0168]dla wartości Aggregate odrzuconej przez schemat filaru — po którym następują ścieżka pola i naruszona reguła schematu. - Błędy warstwy 3 (źródło Provider / Workload) są z definicji przypisywalne do encji katalogu — to para Recipe + Provider utworzyła schemat, który odrzucił dane wejściowe dewelopera. Są one przypisywane do domeny tworzenia katalogu, a to przypisanie trafia do czytelnika w nagłówku diagnostyki w nawiasach kwadratowych, a nie jako słowo wpisane w komunikat: raport przerywający kompilację zaczyna się od
[CATALOG_ERROR E0nnn], gdzie kategoria wskazuje domenę, a krótki kod — warunek. Należy dopasowywać po krótkim kodzie, który po nadaniu się nie zmienia. - Błędy warstwy 4 (walidacja wartości powiązań adnotacji) mają kształt warstwy 2 — walidujący schemat Feature znajduje się w
spec.schemawskazanej encji Feature, a wartości czasu wykonania przepływają przez routingmapspowiązania Manifest do tego schematu w celu sprawdzenia typu na poziomie każdego liścia.
Pełny wykaz sentineli z prefiksem Aggrega i powierzchni, które je generują, znajduje się w errors/error-translation.md. Katalog poszczególnych błędów (reguły kształtu Recipe [CATALOG_ERROR], warunek po warunku) znajduje się w errors/fatal-halts.md.
Interakcja warstw przy nakładających się polach
To samo napisane pole może podlegać więcej niż jednej warstwie. Pole containers.<name>.ports.<port> encji Workload jest sprawdzane przez warstwę 1 jako część struktury schematu Workload; warstwa 2 do niego nie sięga, ponieważ treść Workload jest strukturą wewnętrzną Recipe, a nie filarem Component; a workloadSchema providera niczego nie sprawdza — dlatego ograniczenie takie jak odrzucanie portu poniżej 1024 należy umieścić w schemacie Component lub w asercji, gdzie wskaże je warstwa, która zadziała.
Podsumowanie umiejscowienia w potoku
| Warstwa | Zakres | Uruchamiana w fazie | Prefiks błędu |
|---|---|---|---|
| 1 — koperta JSON Schema | Kształt strukturalny (apiVersion, kind, metadata, spec najwyższego poziomu) | Rozwiązywanie (ładowanie) | kategoria dokumentu z E0215 — [CATALOG_ERROR E0215] dla encji katalogu |
2 — Schematy filarów (schema: / featuresSchema / usesSchema) | Walidacja danych poszczególnych filarów (values, infra, secrets, uses) | Rozwiązywanie (po kopercie) | kategoria dokumentu źródłowego z krótkim kodem warunku — [DEVELOPER_ERROR E0168] dla wartości Aggregate |
| 3 — Bramka możliwości Provider | Obsługa trybu syntetyzowanego (możliwość dostawcy) | Renderowanie bazowe | [CATALOG_ERROR] |
| 4 — Walidacja wartości powiązań adnotacji | Wkłady wartości adnotacji kierowane do spec.schema docelowej encji Feature przez ścieżki maps powiązania w encji Manifest | Podfaza rozwijania adnotacji w ramach rozwiązywania, obok warstwy 2 | błąd walidacji schematu; powierzchnie side-vs-pillar / niejednoznacznego kierowania otwierają własną domenę dokumentu źródłowego — [DEVELOPER_ERROR] z encji Aggregate, [OPS_ERROR] z encji Release |
Odsyłacze
errors/error-translation.md— spis wartości wartowniczych z prefiksem Aggrega oraz miejsc, które je generują.errors/fatal-halts.md— katalog wszystkich krytycznych zatrzymań zgłaszanych przez kompilator, z opisem każdego błędu.vocabulary/data-pillars.md— filary danych (values,infra,parameters,locals,features:,uses:iprovides), które waliduje warstwa 2.entities/component.md— powierzchnia tworzenia encji Component dlaschema:/featuresSchema/usesSchema.entities/plugin.md— powierzchnia tworzenia encji Plugin renderującej dla dostawcy, dotyczącaspec.provider.workloadSchema.entities/manifest.md— powierzchnia wiązaniafeatures.annotationsw encji Manifest (warstwa 4).providers/well-known-annotations.md— parsowanie wartości adnotacji, kierowanie podkluczy wartości strukturalnych, rezygnacja przez null na poziomie podklucza oraz składanie między stronami, które waliduje warstwa 4.