Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Tworzenie w formie zwartej

Forma zwarta to deklaratywny skrót w kształcie YAML dla JSON Schema 2020-12. Autorzy zapisują ograniczenia poszczególnych pól jako mapy YAML w stylu inline-flow (port: { type: integer, min: 1, max: 65535, default: 8080 }); pośrednie węzły obiektów to naturalne zagnieżdżenie YAML; odwołania używają standardowego $ref: z JSON Schema. Kompilator przekształca formę zwartą w JSON Schema 2020-12, zanim zostanie uruchomiona jakakolwiek walidacja, dzięki czemu walidacja, raportowanie błędów i każde narzędzie odczytujące schemat działają na rozwiązanym JSON Schema, niezależnie od formy, w jakiej go napisano.

Ta strona dokumentuje słownictwo formy zwartej, konwencje strukturalne, rozstrzyganie między wywnioskowaną a jawną formą obiektu, semantykę domknięcia, heterogeniczność type: pozwalającą na tablice dozwolonych typów, słowa kluczowe zastrzeżone w każdym zakresie formy wywnioskowanej oraz przestrzeń nazw rozszerzeń x-aggrega-*. Semantykę rozwiązywania $ref: między dokumentami opisuje cross-document-ref.md. Gramatykę tworzenia bloku asercji opisuje templates/assertions-block.md. Zbiór filarów danych (values:, infra:, provides:, uses:, features:, locals:, parameters:) opisuje data-pillars.md.

Forma zwarta jest domyślną powierzchnią tworzenia dla schema:, parameters: oraz wpisów SchemaLibrary. JSON Schema w YAML jest równorzędną opcją tworzenia; obie formy są pełnoprawne i można je mieszać w obrębie jednego schematu. Obie formy kompilują się do tego samego rozwiązanego dokumentu JSON Schema; dalsze narzędzia i walidacja nie rozróżniają ścieżki tworzenia.

Słownictwo

Słowa kluczowe formy kompaktowej to te podane w tabelach poniżej. Autorzy uczą się ich raz i stosują je w schema:, parameters: oraz we wpisach SchemaLibrary.

Słowa kluczowe typu i tożsamości

Słowo kluczoweZnaczenieKompiluje się do JSON Schema
typeTyp pola (string, integer, number, boolean, object, array lub tablica dozwolonych typów)type:
descriptionDokumentacja czytelna dla człowiekadescription:
defaultWartość domyślna, gdy pola brakujedefault:
requiredZnacznik na poziomie liścia (required: true) dla pól, które muszą być obecneDodaje nazwę pola do tablicy required: rodzica

Słowa kluczowe ograniczeń

Słowo kluczoweZnaczenieKompiluje się do JSON Schema
enumDozwolone wartości (lista)enum:
constJedyna dozwolona wartość — skalar, mapa lub listaconst:
minWartość minimalna (liczbowa) lub minimalna długość (ciąg znaków/tablica)minimum: (liczba); minLength: (ciąg znaków); minItems: (tablica) — wybierane na podstawie type:
maxWartość lub długość maksymalna, analogicznie do minmaximum: / maxLength: / maxItems:
minLength / maxLengthJawne ograniczenia długości ciągu znakówBezpośrednie odwzorowanie na minLength: / maxLength: (do użycia, gdy min/max byłyby niejednoznaczne)
patternWzorzec wyrażenia regularnego dla ciągów znakówpattern:
formatNazwany format, który musi mieć ciąg znaków — jeden z email, uri, hostname, ipv4, ipv6, uuid, date-time, date (zob. Nazwane formaty)format:

W bloku parameters: encji Aggregate część z nich jest sprawdzana także w samej deklaracji, zanim zostanie odczytana jakakolwiek wartość encji Release. Własne minLength i maxLength parametru wynoszą zero lub więcej — wartość ujemna jest odrzucana podczas ładowania encji Aggregate — a każdy pattern, także wewnątrz zagnieżdżonego kontraktu items, properties lub valuesType, musi być wyrażeniem regularnym, które się kompiluje, ponieważ wzorzec jest kompilowany podczas odczytu kontraktu parametru. Każdy format, na dowolnej głębokości, musi być jednym z nazwanych formatów poniżej. Odrzucane jest także min lub max przy parametrze typu boolean lub object, ponieważ ta para niczego nie ogranicza w tych typach. Każdy taki błąd zatrzymuje kompilację ze wskazaniem parametru, niezależnie od tego, czy encja Release go dostarcza. Granica długości wewnątrz zagnieżdżonego kontraktu nie podlega temu dolnemu ograniczeniu; miejsce wykonywania każdego sprawdzenia opisuje entities/aggregate.md.

Nazwane formaty

format określa kształt, jaki musi mieć wartość będąca ciągiem znaków. Nazwy są tymi, które definiuje specyfikacja JSON Schema, zapisanymi tak jak w niej, a każda sprawdza to, co według specyfikacji oznacza:

NazwaZgodna wartość toZdefiniowane w
emailskrzynka pocztowa: część lokalna (atomy rozdzielone kropkami lub ciąg w cudzysłowie), @, a następnie domena lub literał adresu w nawiasach kwadratowych — ops@example.com. Nazwa wyświetlana, taka jak Joe <joe@example.com>, nie jest skrzynką pocztowąRFC 5321, sekcja 4.1.2 (Mailbox)
uribezwzględny URI: schemat, :, a następnie reszta, z każdym znakiem spoza alfabetu URI zakodowanym procentowo — https://example.com/a%20b, s3://bucket/key. Odwołanie względne, takie jak /path, nim nie jestRFC 3986 (URI)
hostnamenazwa hosta: etykiety rozdzielone kropkami, złożone z liter, cyfr i łączników, każda o długości 1–63 znaków, nie zaczynająca się ani nie kończąca łącznikiem, łącznie najwyżej 253 znaki — db-primary.data.svc.cluster.local. Etykieta Punycode (xn--…) jest akceptowana w zapisanej postaci; symbol wieloznaczny *, podkreślenie ani kropka na końcu nie sąRFC 1123, sekcja 2.1
ipv4cztery liczby dziesiętne od 0 do 255 rozdzielone kropkami — 192.0.2.1RFC 2673, sekcja 3.2 (zapis kropkowo-dziesiętny)
ipv6adres IPv6 w dowolnej postaci tekstowej — pełnej, skróconej przez :: lub zakończonej adresem IPv4 — 2001:db8::1. Strefa (%eth0) ani długość prefiksu (/64) nie są częścią adresuRFC 4291, sekcja 2.2
uuid32 cyfry szesnastkowe w grupach 8-4-4-4-12 rozdzielonych łącznikami, małymi lub wielkimi literami — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, sekcja 3
date-timeznacznik czasu z przesunięciem — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00 — z dniem istniejącym w danym miesiącu i sekundą przestępną wyłącznie o 23:59 UTCRFC 3339, sekcja 5.6 (date-time)
datedata kalendarzowa — 2026-09-28 — której dzień istnieje w danym miesiącu i rokuRFC 3339, sekcja 5.6 (full-date)

Format ocenia wyłącznie ciąg znaków: wartość innego typu ocenia jej type. Ocenia przy tym tylko składnię wartości — nazwa hosta nigdy nie jest rozwiązywana, URI nigdy nie jest pobierany, a ze skrzynką pocztową nikt się nie kontaktuje — więc sprawdzenie daje ten sam wynik przy każdej kompilacji i nie wymaga sieci.

Sprawdzenie odbywa się wszędzie tam, gdzie wartość jest walidowana względem swojego schematu: w parameters: encji Aggregate, w values i infra ograniczanych przez filary schema: encji Component lub Feature, w values i infra na poszczególnych krawędziach ograniczanych przez schematy ładunku gniazda usesSchema: oraz w każdym wpisie SchemaLibrary, do którego te schematy sięgają. Nazwy formatów filaru provides są oceniane podczas ładowania katalogu, tak jak w każdym innym schemacie; wartości publikowane przez encję Recipe nie są walidowane względem filaru, więc nie sprawdza się w nich żadnego formatu. Wewnątrz allOf, anyOf, oneOf i not wartość niezgodna z formatem jest wartością niespełniającą danej gałęzi, dokładnie tak jak wartość niespełniająca dowolnego innego ograniczenia. Wartość niezgodna jest odrzucana ze wskazaniem pola, wartości i formatu.

Nazwa spoza tabeli jest odrzucana podczas ładowania schematu, niezależnie od tego, czy trafia do niej jakakolwiek wartość, a komunikat odrzucenia wymienia obsługiwane nazwy — dzięki temu literówka, taka jak emial, daje diagnostykę, a nie ograniczenie, które niczego nie sprawdza. W przypadku wpisu SchemaLibrary należy uruchomić aggrega validate na całym katalogu, aby zobaczyć błędną nazwę: encja Release, której schematy sięgają do tego wpisu, również jest odrzucana, ale zgłasza bibliotekę jako nieznalezioną. password nie jest formatem: pole przenoszące dane poufne deklaruje zamiast tego sensitive: true.

Jedno ograniczenie dotyczy kształtów osiąganych pośrednio. Gdy kształt pola pochodzi z $ref:, obok którego stoją inne słowa kluczowe (np. mapa properties:), z then: lub else: w when: albo ze wskaźnika do zadeklarowanej właściwości, jego format jest sprawdzany w polach deklarowanych przez ten kształt bezpośrednio i przez allOf — ale nie wewnątrz anyOf, oneOf, not ani gałęzi warunkowej w obrębie tego kształtu.

Słowa kluczowe kompozycji i odwołań

Słowo kluczoweZnaczenieKompiluje się do JSON Schema
$refOdwołanie do fragmentu JSON Pointer lub zewnętrznego wpisu SchemaLibrary$ref:
allOf / anyOf / oneOfKompozycja JSON SchemaTe same słowa kluczowe
patternPropertiesMapa z kluczami w postaci wyrażeń regularnychTo samo słowo kluczowe
valuesTypeSkrót dla map wartości o określonym typie (np. „obiekt, którego wszystkie wartości są ciągami znaków”)additionalProperties: { type: <X> }

Słowa kluczowe kontenerów

Słowo kluczoweZnaczenieKompiluje się do JSON Schema
itemsKształt elementu tablicyitems: (rekurencyjna forma kompaktowa lub JSON Schema)
propertiesJawna deklaracja elementów podrzędnych (rzadko potrzebna; zwykle wynika ze struktury YAML)properties:
additionalPropertiesCzy dozwolone są niezadeklarowane właściwości (false w obiekcie w formie wywnioskowanej, gdzie dodaje je kompilator; przy jawnym type: object zapisuje się je samodzielnie, a tam, gdzie tego nie zrobiono, obowiązuje domyślna wartość samego JSON Schema, true)additionalProperties:

Słowa kluczowe specyficzne dla Aggrega

Słowo kluczoweZnaczenie
validatePredykat szablonu Go na poziomie pola zwracający wartość logiczną; fałsz zatrzymuje walidację z komunikatem validateMessage:
validateMessageKomunikat błędu towarzyszący niepowodzeniu validate:
whenWarunkowe stosowanie poddrzewa; predykat szablonu Go decydujący, czy ograniczenia węzła mają zastosowanie
sensitiveDeklaruje, że ten liść przenosi dane poufne. Kompiluje się do x-aggrega-sensitive: true. Zob. „Deklarowanie liścia jako poufnego” poniżej
$jsonschemaFurtka — osadzony pełny poddokument JSON Schema w tym węźle
$modeOpcjonalna adnotacja rozstrzygająca dla przypadków niejednoznacznych (rzadko potrzebna; zob. „Forma obiektu wywnioskowana a jawna” poniżej)

Zapożyczone słowa kluczowe JSON Schema ($ref, allOf, format itd.) mają składnię identyczną jak w JSON Schema, więc autorzy znający JSON Schema od razu je rozpoznają.

Słowo kluczowe, którego wartością są dane, przenosi tę wartość tak, jak ją zapisano. Mapa lub lista podana dla default, enum lub const jest samą wartością, nigdy zagnieżdżonym schematem: endpoint: { type: object, default: { host: db, port: 5432 } } ustawia ten obiekt jako domyślną wartość endpoint, a mode: { type: object, const: { kind: fast } } dopuszcza dokładnie ten obiekt — podobnie jak mode: { const: { kind: fast } }, ponieważ const, tak jak enum, samo czyni węzeł liściem. To samo dotyczy wnętrza furtki $jsonschema:.

Struktura liścia w formie kompaktowej

Jednostką tworzenia jest węzeł liścia — pole ze słownikiem ograniczeń:

field_name: { type: <type>, ...constraints... }

Typowe wzorce:

port: { type: integer, default: 8080 }
port: { type: integer, min: 1, max: 65535, default: 8080 }
identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }
log_level: { type: string, enum: [debug, info, warn, error], default: info }
name: { type: string, minLength: 1, required: true }
email: { type: string, format: email }
enabled: { type: boolean, default: false }

Każdy liść zajmuje jeden wiersz. Słownik ograniczeń opisuje wszystko, co dotyczy kształtu pola; struktura węzła nadrzędnego określa położenie pola.

Obiekty zagnieżdżone

Struktura obiektów odzwierciedla zagnieżdżenie YAML. Głębokie zagnieżdżenie działa bezpośrednio, a każdy liść nadal zajmuje jeden wiersz:

spec:
schema:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" }
auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }

Kompilator wnioskuje strukturę obiektów z hierarchii YAML. Węzły pośrednie (tutaj: primary, resources, requests, limits, auth) są typami obiektowymi zawierającymi zagnieżdżone elementy potomne. Kompilator emituje jawne bloki type: object i properties: w rozwiązanym JSON Schema; autor ich nie pisze.

Forma obiektu wywnioskowana a jawna

Zakres obiektu w formie zwartej można zapisać na dwa sposoby:

Forma wywnioskowana — elementy podrzędne bezpośrednio pod kluczem nadrzędnym, bez deklaracji type: object:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

Kompilator rozpoznaje zakres jako obiekt, ponieważ jego elementy podrzędne są deklaracjami właściwości. Emituje type: object, properties: { ... } i automatycznie wstawia additionalProperties: false w czasie kompilacji. Semantyka domknięcia jest częścią kontraktu formy wywnioskowanej: literówki w polach napisanych przez programistę kończą się wyraźnym błędem.

Forma jawna — zadeklarowane type: object, wyliczone properties::

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

W formie jawnej kompilator NIE wstawia additionalProperties: false. Autorzy, którzy deklarują type: object, ponoszą pełną odpowiedzialność za decyzję o domknięciu; forma jawna służy do zapisu rzeczywiście otwartych map (additionalProperties: true) oraz obiektów wymagających innych słów kluczowych JSON Schema (patternProperties, propertyNames, unevaluatedProperties).

Kryterium wyboru: dla zwykłych obiektów domkniętych (typowy przypadek w schematach katalogów) należy używać formy wywnioskowanej. Formy jawnej należy używać, gdy obiekt ma być rzeczywiście otwarty lub gdy schemat wymaga słów kluczowych JSON Schema, których forma zwarta nie obsługuje bezpośrednio.

Semantyka domknięcia

Zgodnie z konwencją obiekty kompaktowej formy w formie wnioskowanej są domknięte: niezadeklarowane właściwości powodują błąd walidacji. Kompilator automatycznie emituje additionalProperties: false w każdym zakresie obiektu w formie wnioskowanej. Odpowiada to dyscyplinie katalogów, w której literówki kończą się głośnym błędem.

Aby otworzyć obiekt (dopuszczając dowolne dodatkowe właściwości), należy użyć formy jawnej z additionalProperties: true:

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

Dla częstego wzorca „obiekt, którego wszystkie wartości mają ten sam typ” (np. mapa string → string dla etykiet) należy użyć valuesType::

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type> kompiluje się do additionalProperties: { type: <type> }. Ten wzorzec występuje na tyle często, że zasługuje na skrót w postaci jednego słowa kluczowego.

Sama nazwa typu powyżej to zapis stosowany w schema: i w SchemaLibrary. W slocie parameters: encji Aggregate wartość należy natomiast zapisać jako kontrakt — valuesType: { type: string }. To samo dotyczy dwóch pozostałych słów kluczowych, których wartość sama jest kontraktem, items: oraz każdego wpisu pod properties:, ponieważ deklaracja parametru i każdy zagnieżdżony w niej kontrakt mają jeden kształt. Sama nazwa typu na którejkolwiek z tych trzech pozycji w slocie parametru jest odrzucana, a diagnostyka wskazuje, który zagnieżdżony kontrakt ją zawierał. Pełne słownictwo slotów parametrów opisuje entities/aggregate.md.

Pola wymagane

Pola wymagane oznacza się przez required: true przy każdym liściu:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }

Kompilator zbiera wszystkie znaczniki required: true w zakresie obiektu i emituje je jako tablicę required: [field1, field2] z JSON Schema. Znacznik jest uwzględniany wszędzie tam, gdzie zadeklarowano właściwość: w zakresie formy wnioskowanej oraz przy właściwości wewnątrz jawnego bloku properties:.

Konsument, który włącza wpis z SchemaLibrary do swojego schematu przez $ref:, może wskazać wymagane pola na dowolny z dwóch sposobów — tablicą required: [name1, name2] na poziomie rodzica obok odwołania albo znacznikiem required: true przy właściwości, którą deklaruje tam pod properties:. Pełną regułę opisuje cross-document-ref.md, §„Składnia required: przy $ref: między dokumentami”.

Tablice

Tablice używają type: array z items: opisującym kształt elementu:

tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars:
type: array
items:
name: { type: string, required: true }
value: { type: string }
valueFrom: { type: object, additionalProperties: true }
allowedHosts:
type: array
min: 1 # minItems
max: 100 # maxItems
items: { type: string, format: hostname }

W typowym przypadku „tablicy typowanych wartości skalarnych” forma wbudowana zajmuje jeden wiersz. W przypadku tablic obiektów items: wprowadza zagnieżdżony schemat w formie zwartej.

Słowo kluczowe type: — skalar lub tablica typów

type: przyjmuje pojedynczą wartość (type: string) albo tablicę dozwolonych typów (type: [string, integer, boolean]). Forma tablicowa to standardowy w JSON Schema 2020-12 sposób wyrażenia „to pole przyjmuje jeden z kilku typów”:

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

Gdy type: zawiera tablicę, przestrzeń wartości jest sumą przestrzeni wartości wymienionych typów. Autorzy schematów korzystających z formy tablicowej muszą dalej obsłużyć oba kształty — pole type rozwiązanego JSON Schema zawiera albo ciąg znaków, albo tablicę, a konsumenci przechodzący rozwiązany schemat sprawdzają oba kształty.

Słowa zastrzeżone w każdym zakresie formy wnioskowanej

Rozpoznawanie formy wnioskowanej uwzględnia niewielki zestaw słów kluczowych, które mają znaczenie na poziomie słownika formy kompaktowej: description, type, default, required, słowa kluczowe ograniczeń (enum, const, min, max, pattern, format itd.) oraz słowa kluczowe specyficzne dla Aggrega (validate, validateMessage, when, sensitive). Gdy którekolwiek z tych słów kluczowych występuje jako nazwa pola w zakresie obiektu formy wnioskowanej, kompilator odczytuje otaczający zakres jako liść z ograniczeniami, a nie jako obiekt: słowo kluczowe jest traktowane jako ograniczenie, a nie jako właściwość podrzędna, a każdy inny klucz w tym zakresie musi wtedy również być słowem kluczowym, więc pierwszy, który nim nie jest, zostaje odrzucony jako nieznane słowo kluczowe.

sensitive zasługuje tu na szczególną uwagę, ponieważ jest znacznie bardziej prawdopodobną nazwą rzeczywistego pola tworzonego przez programistę niż pozostałe słowa kluczowe specyficzne dla Aggrega. Schemat, który rzeczywiście potrzebuje właściwości o nazwie sensitive — na przykład komponent, którego values udostępniają własną flagę sensitive — musi jawnie zadeklarować otaczający zakres, dokładnie tak, jak w przypadku właściwości o nazwie type lub default. Można to osiągnąć formą jawną przedstawioną poniżej albo za pomocą $mode: jsonschema w otaczającym zakresie: przy $mode: jsonschema cały węzeł jest odczytywany jako napisany ręcznie JSON Schema, w którym sensitive jest zwykłą treścią, a nie słowem kluczowym formy kompaktowej.

W schematach, które potrzebują właściwości nazwanej tak jak słowo zastrzeżone (np. kontrakt encji Component z polem description: tworzonym przez programistę, polem type: lub polem default:), należy użyć formy jawnej dla problematycznego zakresu:

spec:
schema:
values:
type: object
properties:
description: { type: string } # property named "description"
type: { type: string } # property named "type"
default: { type: string } # property named "default"
required: [description, type]
additionalProperties: false

Forma jawna omija rozpoznawanie — properties: jawnie wylicza elementy podrzędne, więc kolizja ze słowem kluczowym nie występuje.

To ograniczenie obowiązuje rekurencyjnie w każdym zakresie formy wnioskowanej. Zagnieżdżony obiekt formy wnioskowanej zawierający właściwość nazwaną tak jak słowo zastrzeżone jest w tym zakresie odczytywany jako liść z ograniczeniami. Rozwiązanie jest takie samo: należy przełączyć problematyczny zakres na formę jawną.

Odwołania

Odwołania przejmują $ref: ze JSON Schema zarówno składniowo, jak i semantycznie:

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

Bloki $defs: w schemacie w formie zwartej deklarują definicje wielokrotnego użytku. Każdy wpis sam jest schematem w formie zwartej (albo JSON Schema, albo mieszanym). Odwołanie następuje przez fragment JSON Pointer #/$defs/<Name>:

Blok należy zadeklarować wewnątrz filaru, którego pola się do niego odwołują, obok tych pól — nie obok filaru. Blok schema: przyjmuje na swoim najwyższym poziomie tylko nazwy trzech filarów danych, więc $defs: zapisany jako element równorzędny values: zostaje odrzucony podczas ładowania encji, z podaniem błędnego klucza i zbioru filarów, jakie może zawierać. Wskaźnik w obu przypadkach zapisuje się jako #/$defs/<Name>.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }

Odwołania między dokumentami wskazujące wpisy SchemaLibrary opisano w cross-document-ref.md. Rozwijanie skróconych URI OCI opisano w uri-grammar.md.

Odwołanie powinno wskazywać definicję, a nie właściwość

Wskaźnik wskazujący wpis $defs: — #/$defs/PodResources — to kształt, po który należy sięgać. Wskaźnik jest dozwolony wszędzie tam, gdzie dopuszcza go JSON Schema, więc wskaźnik do zadeklarowanej właściwości również jest akceptowany i egzekwowany, ale jest raportowany mniej precyzyjnie, a tę różnicę warto znać przed jego zapisaniem.

Pole, którego kształt pochodzi z wpisu $defs:, jest sprawdzane pole po polu: błąd jest raportowany pod ścieżką wartości, która faktycznie jest błędna, i raportowane są wszystkie błędy w tym polu, a nie tylko pierwszy.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

Błędna wartość cpu jest tu raportowana pod primary.resources.requests.cpu.

Pole, którego kształt pochodzi ze wskaźnika do zadeklarowanej właściwości, jest sprawdzane jako część dokumentu jako całości. Ograniczenia nadal obowiązują, a dokument, który je narusza, nadal zatrzymuje kompilację — ale błąd jest raportowany pod polem zawierającym wskaźnik, a nie pod wartością wewnątrz niego, a gdy kilka takich pól jest błędnych jednocześnie, wskazywane jest tylko jedno z nich.

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

Błędna wartość cpu w secondary jest raportowana pod secondary.resources.

Oba sposoby zapisu akceptują i odrzucają te same dokumenty, z wyjątkiem jednego ograniczenia dotyczącego format, opisanego w Nazwanych formatach: przez wskaźnik format wewnątrz gałęzi anyOf, oneOf lub not kształtu nie jest sprawdzany. Poza tym różni się jedynie to, ile informacji niesie komunikat, co ma największe znaczenie w edytorze, gdzie znacznik jest umieszczany na podstawie tej ścieżki. To samo dotyczy wpisu $defs:, którego własny wskaźnik sięga z powrotem do właściwości: dotarcie do definicji przez niego dziedziczy mniej dokładny raport.

Warunkowy kształt za pomocą when:

JSON Schema 2020-12 wyraża warunkowy kształt za pomocą if/then/else. Forma kompaktowa udostępnia when: jako bardziej bezpośredni skrót: predykat szablonu Go, który, jeśli jest prawdziwy, stosuje pozostałe ograniczenia węzła; jeśli jest fałszywy, węzeł jest traktowany tak, jakby jego ograniczenia nie istniały.

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

Predykat jest wyliczany względem wartości instancji elementu nadrzędnego. $ odnosi się do otaczającego zakresu obiektu. Gdy architecture ma wartość replication, ograniczenia (required: true, dodatkowe replicaCount: min: 2) obowiązują dodatkowo względem przywoływanego NodePool. Gdy architecture ma wartość standalone, te ograniczenia są nieaktywne.

Predykat ma dostęp do standardowych funkcji szablonów Go (Sprig). Kompilator kompiluje when: do if/then/else z JSON Schema wraz z otoczką, która wylicza predykat szablonu Go przed uruchomieniem walidacji. Determinizm zostaje zachowany, ponieważ predykat jest czysty względem instancji.

Niestandardowa walidacja pojedynczego pola za pomocą validate: i validateMessage:

Niektórych ograniczeń nie da się wyrazić za pomocą min / max / pattern / enum. Dla takich przypadków forma kompaktowa udostępnia validate: — predykat szablonu Go, który, jeśli jest fałszywy, przerywa walidację z niestandardowym błędem.

db_size:
type: string
pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$"
validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}'
validateMessage: "db_size must exceed 100 in its declared unit"

Predykat jest wykonywany względem wartości pola (dostępnej jako .); zakresem otaczającego obiektu jest $. Jeśli predykat zwróci fałsz, walidacja zgłasza błąd z użyciem validateMessage: (lub komunikatu domyślnego, jeśli go nie podano).

validate: obsługuje przypadki wykraczające poza standardowe słownictwo JSON Schema: niestandardową walidację semantyczną (sprawdzanie formatu semver, zawartość JSON w ciągu znaków), reguły międzypolowe o wąskim zakresie, w których ograniczenie jednego pola zależy od pola sąsiedniego, oraz ograniczenia, dla których nie warto tworzyć pełnego bloku assertions:.

validate: różni się od when: rolą: when: przełącza, czy ograniczenia mają zastosowanie; validate: samo jest ograniczeniem.

W przypadku rzeczywiście międzypolowych reguł o szerokim zakresie, w których żadne pojedyncze pole nie jest „tym walidowanym”, należy użyć dedykowanego bloku assertions:. Zob. templates/assertions-block.md.

Deklarowanie liścia jako wrażliwego — sensitive:

Liść values, infra lub provides może zadeklarować, że opisywana przez niego dana zawiera materiał tajny:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true
description: "The credential material itself."
key:
type: string
default: value
description: "The data key the material is stored under."

sensitive: true kompiluje się do słowa kluczowego rozszerzenia x-aggrega-sensitive: true w tym węźle rozwiązanego JSON Schema, obok pozostałych adnotacji x-aggrega-*. Kompilator odczytuje je, aby ustalić, które dołączenia we wdrożeniu obsługują materiał zadeklarowany jako wrażliwy, i przenosi ten wyprowadzony fakt w skompilowanym grafie.

Deklarację należy umieszczać przy danej, a nie przy jej lokalizatorze. To rozróżnienie jest całym sensem słowa kluczowego i łatwo je odwrócić. Wrażliwy jest materiał poświadczenia; nazwa zasobu, który je przechowuje, i klucz danych w tym zasobie nie są — oba są publiczne i oba są renderowane jawnie w każdym konsumencie, który odwołuje się do zasobu. Oznaczenie lokalizatora stwierdza o nim coś nieprawdziwego i przenosi ten błąd na wszystko dalej, co odczytuje deklarację. W powyższym przykładzie origin jest oznaczony, a key celowo nie.

Stwierdzenie uzupełniające — cokolwiek zostanie powiązane z tym punktem, obsługuje materiał tajny, niezależnie od tego, co wypełnienie deklaruje o własnych liściach — w ogóle nie jest deklaracją liścia. Jest to sensitive na slocie dołączenia; zob. entities/component.md „Attachment Slots”.

Deklarowanie całego obiektu jako wrażliwego

Słowo kluczowe może stać przy obiekcie zamiast przy skalarze i wtedy obejmuje wszystko poniżej tego obiektu — jego dzieci i wszystko zagnieżdżone głębiej. Tej deklaracji należy użyć, gdy materiałem jest cały blok, a oznaczanie każdego liścia osobno zostawiłoby nieoznaczony kolejny liść, który ktoś doda.

Dzieci obiektu muszą znajdować się w jawnym bloku properties:. To jedyne miejsce, w którym forma obiektu wywnioskowanego nie wystarcza, a powód warto znać, zamiast go obchodzić:

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

Zapisanie dzieci bezpośrednio obok znacznika, tak jak forma obiektu wywnioskowanego pozwala wszędzie indziej, jest odrzucane w czasie kompilacji — pierwsze dziecko zostaje zgłoszone jako nieznane słowo kluczowe, ze wskazaniem na własny klucz dziecka:

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

Odrzucenie jest poprawne, a nie jest ograniczeniem do obejścia. Węzeł jest odczytywany jako liść z ograniczeniami, gdy tylko zawiera słowo kluczowe formy kompaktowej, a sensitive: nim jest — więc od tego momentu każdy klucz sąsiedni też musi być słowem kluczowym, a password nim nie jest. Blok properties: mówi: „klucze poniżej są nazwami właściwości, a nie kolejnymi słowami kluczowymi”, i jest to to samo rozróżnienie, które opisuje Forma obiektu wywnioskowana a jawna. Odczytanie diagnostyki jako „znacznik nie może stać przy obiekcie” to błędna interpretacja, której należy unikać: może, a blok jest sposobem, by to wyrazić.

Liść wewnątrz zadeklarowanego obiektu nie potrzebuje własnego znacznika. Dodanie go jest nieszkodliwe i nie wnosi nic nowego, ponieważ deklaracja obiektu już go obejmuje.

Czego słowo kluczowe nie robi

Nazwa sugeruje założenia, na które słowo kluczowe nie zasługuje, dlatego granice należy określić wprost:

  • Niczego nie szyfruje. Jest adnotacją przy deklaracji, a nie mechanizmem poufności.
  • Nie waliduje ani nie odrzuca, z wyjątkiem wypełniania parametrów szablonu CloudFormation. Żadna wartość nie jest przyjmowana ani odrzucana dlatego, że liść zadeklarowano jako wrażliwy, i żaden wynik budowania się nie zmienia — z tym wyjątkiem, że gdy valuesMapping encji Recipe lub FeatureRecipe dla CloudFormation odczytuje liść zadeklarowany jako wrażliwy, aby wypełnić parametry pobranego szablonu, każdy literał wiązany przez to mapowanie zatrzymuje budowanie, więc dwa budowania różniące się tylko deklaracją mogą zakończyć się inaczej. Zob. A secret bound to a CloudFormation parameter would be written into the template (Sekret powiązany z parametrem CloudFormation zostałby zapisany w szablonie).
  • Nie gwarantuje, że renderowany wynik jest wolny od materiału. To, czy artefakt zawiera materiał, zależy od tego, które wypełnienie autor dołączył i co zapisał w jego values — zob. architecture/08-credential-model.md „What the compiler does and does not guarantee”. Wartość zadeklarowana jako wrażliwa, którą autor podał bezpośrednio, jest renderowana dokładnie tak samo jak niezadeklarowana, wszędzie tam, gdzie budowanie w ogóle ją renderuje.
  • Nie wymusza mechanizmu dostarczania. Nie może zamienić wartości podanej bezpośrednio na odwołanie do magazynu i nie zawęża tego, na co pozwala lista dozwolonych inject slotu.
  • Nie zatrzymuje budowania, z wyjątkiem wspomnianego odrzucenia CloudFormation. Powiadomienia zgłaszane w czasie budowania, opisane niżej, są ostrzeżeniami: budowanie dochodzi do końca i zapisuje swoje artefakty. Uczynienie powiadomienia krytycznym jest wyborem organizacji, wyrażonym jako polityka zarządcza dołączona do budowania, a nie czymś, co słowo kluczowe robi samo. Wyjątkiem jest opisane wyżej odrzucenie przez dostawcę CloudFormation: zatrzymuje ono budowanie, ponieważ literał zapisany w szablonie może odczytać każdy, kto może odczytać stos.
  • Na większości platform docelowych nie zmienia żadnego renderowanego bajtu i na nich nigdy nie zmieni. Platforma docelowa, która ma własne pojęcie wrażliwości, to miejsce, w którym deklaracja ma gdzie trafić; platforma bez takiego pojęcia nie ma niczego, co deklaracja mogłaby zmienić, na stałe. Terraform jest jedyną platformą docelową biblioteki standardowej z takim prymitywem: gdy wejście dołączonego modułu przyjmuje materiał, który autor zadeklarował jako wrażliwy, renderowany wynik zyskuje wygenerowany plik nadpisania, ustawiający dla tego wejścia własny atrybut wrażliwości Terraform — zob. providers/terraform.md „Declared-sensitive module inputs”. Wszędzie indziej zadeklarowanie liścia jako wrażliwego w istniejącym katalogu pozostawia każdy renderowany artefakt bez zmian.

Co zmienia w tym, co wypisuje narzędzie

Jedyne, co deklaracja faktycznie zmienia, to to, co narzędzie wypisuje do odczytu przez człowieka: jego wyjście diagnostyczne oraz tekst odrzucenia, opisany niżej. Na powierzchniach diagnostycznych wartość zadeklarowana jako wrażliwa jest zastępowana stałym tekstem <redacted>:

  • ślad dla poszczególnych przebiegów, który aggrega build --trace zapisuje do .trace/;
  • blok Values: dla poszczególnych węzłów, który aggrega inspect wypisuje dla encji Aggregate;
  • blok dołączeń dla poszczególnych liści, który aggrega inspect wypisuje dla rozwiązanej encji Release.

Klucz jest zawsze zachowywany, a zastępowana jest tylko jego wartość, więc czytelnik nadal widzi, że liść został zapisany i że coś ukryto. Liść, którego autor nie zadeklarował, wypisuje swoją wartość dosłownie obok ukrytego sąsiada — zastąpienie wynika z deklaracji i z niczego innego, więc pole o nazwie password bez deklaracji jest wypisywane, a zadeklarowane pole o nazwie key nie jest.

Deklaracja obejmuje każdy liść poniżej i obejmuje wszystkie trzy powierzchnie w ten sam sposób. Gdy deklaracja stoi przy obiekcie, każda wartość zagnieżdżona w tym obiekcie jest również ukrywana, na dowolnej głębokości — deklaracja obiektu je wskazuje, więc ich ukrycie nie stwierdza niczego, czego autor nie zapisał. Dopasowanie dotyczy całych segmentów ścieżki, a nie tekstu, więc sąsiad, którego nazwa jedynie zaczyna się od zadeklarowanej nazwy, pozostaje nietknięty: zadeklarowanie dbPassword nie ukrywa dbPasswordHint.

Ukrywanie w śladzie można wyłączyć dla jednego budowania, gdy debugowana jest właśnie ukryta wartość: aggrega build --trace --trace-unredacted zapisuje wartości w plikach śladu i oznacza każdy z tych plików nagłówkiem, który o tym informuje. Jest to wybór dokonywany przy wywołaniu, bez ustawienia konfiguracyjnego, dotyczy wyłącznie śladu i jest opisany w cli/aggrega-build.md „Showing the withheld values”. Widoki aggrega inspect mają własną opcję, --unredacted, opisaną w cli/aggrega-inspect.md „Showing the withheld values”.

Granice tego zachowania są ważniejsze niż samo zachowanie.

Wyrenderowane artefakty nigdy nie są redagowane. Wszystko w dist/ jest emitowane dokładnie tak, jak wytworzył to render, ponieważ jest to wdrażalny wynik: symbol zastępczy zapisany w manifeście oznaczałby zepsute wdrożenie, a nie chronione. Redakcja obejmuje to, co narzędzie wypisuje, nigdy to, co zapisuje. Odczytywanie deklaracji jako obietnicy, że zawartość dist/ można bezpiecznie opublikować, jest tym błędnym odczytaniem, którego należy unikać — opisany wyżej pułap pozostaje bez zmian, a dist/ jest tak samo wrażliwy jak jego dołączenie przenoszące najwięcej poufnego materiału.

Jedna rzecz, którą deklaracja może dodać do wyrenderowanego artefaktu, i nie jest to redakcja: jeśli cel ma własny prymityw wrażliwości, deklaracja jest w nim renderowana. Wartość jest nadal zapisywana w całości — nic nie jest wstrzymywane ani zastępowane — a artefakt zyskuje obok niej własne oznaczenie celu, dzięki czemu narzędzia celu mogą traktować wartość tak, jak zadeklarował ją autor. Obecnie oferuje to Terraform, a to, co jego atrybut gwarantuje, a czego nie, opisano w providers/terraform.md „Declared-sensitive module inputs”. Takie oznaczenie trafia wyłącznie tam, gdzie tożsamość wyrenderowanej nazwy daje się odtworzyć z samej deklaracji; jeśli nazwę wymyślił szablon, oznaczenia nie ma, zamiast go przybliżać, ponieważ oznaczenie wartości, której autor nie zadeklarował, stwierdzałoby o niej coś nieprawdziwego. Jeśli tym szablonem jest valuesMapping — encji Recipe albo encji FeatureRecipe encji Feature dołączonej do komponentu — build to zgłasza, jak opisano poniżej.

Redakcja obejmuje to, co nazywa deklaracja, oraz to, co według odczytu czyta szablon. Zadeklarowany liść w filarze values lub infra oraz klucz dostarczania przenoszący materiał z klucza provides zadeklarowanego jako wrażliwy są identyfikowane po nazwie i wstrzymywane. Wartość obliczona przez szablon trafia pod klucz, którego nikt nie zadeklarował, więc identyfikuje ją zamiast tego referencja zapisana przez autora: w śladzie wstrzymywany jest wpis locals: lub pole source:, którego szablon czyta liść zadeklarowany jako wrażliwy, a także wpis locals: czytający już wstrzymany element sąsiedni. Odczyt jest celowo zachowawczy — sięgnięcie do całego obiektu sięga do każdego zadeklarowanego liścia pod nim, a szablon przekazujący dalej całość swoich danych sięga do nich wszystkich — więc nierozwiązywalna referencja powoduje wstrzymanie, a nie wypisanie.

Wyrenderowany dokument jest pokazywany jako ponowny render i jest to wyraźnie oznaczone. Sparsowany Workload w śladzie to dokument wytworzony przez szablon encji Recipe: nic w nim nie rejestruje, z której deklaracji pochodzi każdy znak, więc nie ma w nim klucza, pod którym można by dokonać podstawienia, a odtwarzanie powiązania pole po polu oznaczałoby badanie treści wartości — czego kompilator nie robi. Zamiast tego ślad pokazuje ten sam szablon workload: wyewaluowany ponownie w kontekście, w którym dane zadeklarowane jako wrażliwe są już odczytywane jako tekst zastępczy, co ogłasza wpis workload_note obok dokumentu. Ponieważ szablon widzi ciąg znaków tam, gdzie był ciąg znaków, ponowny render zachowuje kształt wyemitowanego dokumentu, a tekst zastępczy stoi na własnej pozycji wstrzymanej danej. Pozostają dwie różnice i notka podaje obie: szablon rozgałęziający się na podstawie treści wartości renderuje się inaczej z tekstem zastępczym, a dana, której oś nie nazywa, przechodzi bez zmian. Jest to widok debugowania tego, co wyrenderowano, nigdy jego kopia.

Wartości konsumowanego węzła są wstrzymywane według deklaracji tego węzła, na obu powierzchniach, na które przenosi je krawędź. Widok krawędzi uses odtwarza to, co opublikował komponent docelowy, więc rządzi nim własny schemat celu: klucz provides zadeklarowany przez cel jako wrażliwy jest wstrzymywany w śladzie konsumenta, nawet gdy konsument niczego nie deklaruje. Jeśli własny blok inject krawędzi kieruje ten klucz na klucz dostarczania komponentu konsumującego, ten klucz dostarczania również jest wstrzymywany — to ta sama reguła, którą stosuje mapowanie inject dołączenia, czytająca tę samą deklarację, więc oba połączenia nie mogą być ze sobą sprzeczne. Układy aggrega inspect pokazują własne filary węzła i jego dołączenia, a nie opublikowane wartości konsumowanego węzła, więc nic tam nie przenosi widoku międzywęzłowego, który trzeba by wstrzymać.

Dołączenie zapisane na połączeniu jest wstrzymywane według deklaracji jego własnej encji Feature, na każdej powierzchni, która je pokazuje. Ślad pokazuje je w widoku krawędzi uses tego połączenia, pod .context.uses.<alias>.features.<slot>, a aggrega inspect wypisuje je pod wierszem połączenia w rozwiązanej encji Release. Na obu liść values lub infra, który jego Feature deklaruje jako wrażliwy, jest wstrzymywany dokładnie tak samo jak w tej samej encji Feature dołączonej bezpośrednio do komponentu, a w śladzie wstrzymywany jest także klucz rozwiązanego provides dołączenia, który Feature deklaruje jako wrażliwy. Jego typ, wersja, etykiety oraz każdy niezadeklarowany liść i klucz provides są wypisywane dosłownie, więc opublikowany lokalizator pozostaje czytelny obok materiału, który lokalizuje. Slot deklarujący sensitive: true, na komponencie lub na gnieździe, oznacza dołączenie jako obsługujące tajny materiał i sam z siebie nie wstrzymuje żadnego liścia — o tym, które liście są wstrzymywane, decyduje deklaracja encji Feature.

Projekcje do odczytu maszynowego są z założenia dosłowne i wymagają takiego samego traktowania jak pliki, z których pochodzą. aggrega inspect --raw emituje encję dokładnie tak, jak ją napisano, a aggrega inspect --output yaml odtwarza napisaną encję dla każdego rodzaju, łącznie z Release. Żadne z nich niczego nie podstawia i jest to celowe: są to wyjścia, które parsuje skrypt i porównuje diff, więc wyjście po cichu wstrzymujące część siebie przeinaczałoby dane wejściowe, które ma odtwarzać, i psułoby pełny obieg, na którym polegają jego konsumenci. Zadeklarowanie liścia jako wrażliwego nie wystarcza, by wykluczyć go z tych wyjść: należy je przekazywać potokiem, przechowywać i udostępniać tak samo jak same encje Aggregate i Release.

Skompilowany graf jest jedyną projekcją do odczytu maszynowego, która wstrzymuje wartości, gdziekolwiek jest udostępniany. --ir-graph w aggrega inspect, aggrega validate i aggrega build zapisuje graf rozwiązany w danym uruchomieniu jako JSON obok tego, co polecenie już wytwarza, a aggrega/irGraph demona odpowiada edytorowi tym samym grafem; w każdym z tych przypadków wartość zadeklarowana przez autora jako wrażliwa jest zastępowana dokładnie tak jak w układach do odczytu. --unredacted obok --ir-graph wypisuje zamiast tego te wartości, podobnie jak pole unredacted w żądaniu do demona. Graf odczytany z polecenia i graf odczytany przez protokół demona to zatem ten sam dokument objęty tą samą regułą traktowania, a potok lub klient potrzebujący napisanych wartości musi o nie poprosić.

Co odmowa mówi o zadeklarowanej wartości

Odmowa zgłoszona przez szablon, który odczytuje wartość zadeklarowaną przez autora jako wrażliwą, nie zawiera tej wartości. Gdy szablon zatrzymuje kompilację — asercja wywołująca fail, wyrażenie, którego nie da się obliczyć, wynik, który nie odczytuje się jako dokument, jaki szablon musi wytworzyć — a jedno z jego odwołań sięga danej zadeklarowanej jako wrażliwa, zgłaszana treść pochodzi z ponownego obliczenia tego samego szablonu w kontekście, w którym każda dana zadeklarowana jako wrażliwa ma już wartość <redacted> — chyba że szablon zatrzymał się na zdaniu, które sam zapisuje w całości, czyli w pierwszym przypadku poniżej:

assertion failed: the admin password <redacted> must be supplied as a reference
  • Wywołanie fail, którego zdanie jest w całości zapisane w szablonie, jest zgłaszane tak, jak je zapisano. Gdy wywołaniem, które zatrzymało kompilację, jest fail z jednym ciągiem w cudzysłowie — fail "…", bez niczego przekazanego do niego potokiem i bez niczego wstawionego do jego zdania — odmowa zawiera to zdanie niezależnie od zawartości wartości i od tego, która gałąź doprowadziła do wywołania, ponieważ zdanie nie cytuje niczego, co szablon odczytał: asercja odrzucająca źródło o niewłaściwej postaci pokazuje własne wyjaśnienie tej postaci. Zdanie zbudowane w jakikolwiek inny sposób — printf, pole, zmienna, wartość przekazana potokiem do fail — jest zgłaszane zgodnie z przypadkami opisanymi dalej.
  • Jeśli drugie obliczenie kończy się niepowodzeniem w tym samym wyrażeniu z tego samego powodu, zgłaszany jest jego błąd. Zdanie autora zostaje zachowane z <redacted> w miejscu wartości, a wartość, którą szablon zakodował, ujął w cudzysłów lub w inny sposób przekształcił, również jest ukryta, ponieważ zastąpienie następuje przed przekształceniem.
  • Jeśli tak nie jest, odmowa wskazuje wyrażenie, które zawiodło, i informuje, że jego tekst jest ukryty. Jest to szablon, którego zachowanie zależało od zawartości wartości — wobec tekstu zastępczego wybrał inną gałąź lub zawiódł w innym miejscu — więc nic, co złożył, nie może zostać pokazane. Aby taka odmowa sama się wyjaśniała, należy zapisać jej zdanie w całości w wywołaniu fail, jak opisuje pierwszy przypadek. Odmowa nadal zatrzymuje kompilację i zachowuje swój kod.
  • Wyrenderowany Workload odrzucony przez schemat Workload jest opisywany na podstawie schematu. Pola dokumentu nie zawierają powiązania z danymi odczytanymi przez jego szablon, więc jeśli szablon odczytał daną zadeklarowaną jako wrażliwa, każde ustalenie, które mogłoby cytować wartość, podaje zamiast tego ograniczenie, z <redacted> w miejscu wartości i informacją wyjaśniającą powód. Nie podaje się żadnej porady wynikającej z wartości, a ustalenie niecytujące żadnej wartości — brakujący klucz, klucz niedopuszczany przez Workload — brzmi jak zawsze:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)
  • Wejście with kroku potoku odrzucone przez zadeklarowany kontrakt wejściowy kroku jest opisywane na podstawie kontraktu, jeśli szablon with odczytuje daną zadeklarowaną jako wrażliwa: każda błędna pozycja w wejściu i słowo kluczowe schematu, które ją odrzuciło, a po nich informacja wyjaśniająca powód — i nic z tego, co zawierało wejście.
  • Odmowa wskazująca współrzędną source: jest opisywana na podstawie tego, co wytworzyły elementy niezadeklarowane, jeśli szablon source: wytworzył tę współrzędną, odczytując daną zadeklarowaną jako wrażliwa — źródła nie ma w pliku blokady ani w pamięci podręcznej, jego archiwum w pamięci podręcznej nie zgadza się z zapisem w pliku blokady albo przypięcie zapisane obok encji jest niezgodne z plikiem blokady. Każdy wiersz takiej odmowy podaje współrzędne użyte przy wyszukiwaniu, więc wskazuje źródło przez jego url oraz wersję lub referencję, o którą zapytano — tam, gdzie je odczytała — z <redacted> w miejscu każdej wytworzonej przez taki szablon, i informuje, że jej powód jest ukryty. Zachowuje swój kod i środek zaradczy, który kompilacja podaje dla tego kodu:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template produced

Za zadeklarowane uznaje się to, co wskazują deklaracje, w każdej części kontekstu, którą szablon może odczytać: własne values i infra komponentu, encje Features dołączone do niego i do każdego z jego połączeń, klucz dostarczania przenoszący zadeklarowany materiał, klucz provides, który jego encja Component deklaruje jako wrażliwy, każdy wpis listy przenoszonej przez kontekst, opisany poniżej, oraz wpis locals: obliczony z dowolnego z nich. Szablon, który nie odczytuje żadnego z nich, zgłasza błąd dokładnie tak, jak bez żadnej deklaracji, bajt w bajt, więc inaczej zgłaszana jest tylko odmowa szablonu, który odczytał zadeklarowaną wartość. Odczyt jest taki sam jak w śladzie i opiera się na odwołaniach zapisanych w szablonie: sięgnięcie do całego obiektu sięga każdego zadeklarowanego liścia pod nim, więc może ukryć tekst, który nie zawierał żadnej wartości. Szablon przekazujący naraz całość swoich danych — kropkę lub $ bez niczego dalej, przekazane do funkcji takiej jak toJson, wypisane lub przekazane do szablonu wywoływanego po nazwie — odczytuje każdą zawartą w nich zadeklarowaną wartość, więc jego odmowa jest zgłaszana w ten sam sposób; wewnątrz ciała range lub with kropka jest wartością, po której to ciało iteruje lub którą nazywa, a jej przekazanie odczytuje tylko to, co ta wartość zawiera. Nic tutaj nie zależy od --trace-unredacted: ta flaga dotyczy wyłącznie plików śladu, a odmowa brzmi tak samo z nią i bez niej.

Zadeklarowana wartość jest ukrywana wszędzie, gdzie się znajduje, także wewnątrz listy. Wpisy jednej listy podlegają różnym encjom, a każdy wpis jest ukrywany zgodnie z deklaracjami własnej encji. W widoku .boundary, który odczytuje encja FeatureRecipe obejmująca całą granicę, każde połączenie wymienione w internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges i cross_boundary_uses_edges przenosi provides publikowane przez jego cel, ukrywane tam, gdzie encja Component celu deklaruje klucz jako wrażliwy, a każdy wpis feature_attachments przenosi infra tego załącznika, ukrywane tam, gdzie jego Feature deklaruje liść. W kontekście encji Feature dołączonej do komponentu każdy wpis .context.used_by przenosi to, co publikuje łączący się komponent, ukrywane tam, gdzie encja Component łączącego się komponentu deklaruje klucz. Ten sam klucz we wpisie, którego encja niczego nie deklaruje, jest cytowany bez zmian, a wpis locals: obliczony z ukrytego wpisu jest ukrywany razem z nim. Iterowanie po liście lub sięgnięcie do jednego z jej wpisów przez index odczytuje całą listę, więc liczy się jako odczyt tego, co przenosi każdy wpis:

error calling fail: target secret_ref "<redacted>" must start with ref-

Dotyczy to tekstu odmowy zgłaszanej przez kompilację. To, co dostawca otrzymuje jako informację o tym, która część jego danych wejściowych pochodzi z zadeklarowanej wartości — wartości wygenerowane przez valuesMapping, wyrenderowany dokument workload:, każdy wpis artifacts:, każde pole wpisu omits: — nie uwzględnia wartości odczytanej z wnętrza listy, więc własna obsługa zadeklarowanej wartości przez dostawcę, łącznie z opisaną wyżej odmową CloudFormation dla powiązanego literału, takiej wartości nie obejmuje.

Niektóre odmowy pozostają poza tym mechanizmem. Tekst zapisany przez plugin — własna odmowa dostawcy lub kroku potoku — jest zdaniem pluginu, przekazywanym tak, jak plugin je zapisał. Szablon obliczany poza asercjami i renderowaniem kompilacji — interpolacja parametrów i sprawdzanie parametrów w encji Aggregate, szablony when: i validate: schematu oraz rozwiązywanie współrzędnej source:, które zapisuje jej przypięcie — zgłasza błąd tak, jak wystąpił.

Ostrzeżenie kompilacji o wartości przekazywanej jako literał

Kompilacja wypisuje jedno ostrzeżenie na każdy klucz dostarczania, który przenosi materiał zadeklarowany jako wrażliwy w postaci wartości literalnej. Pojawia się, gdy blok inject dołączenia kieruje klucz provides, zadeklarowany jako wrażliwy przez encję Feature dołączenia, na klucz dostarczania komponentu konsumującego, a wartość zostaje faktycznie dostarczona:

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

Trzy jego cechy są celowe.

Informuje, jak wartość jest przekazywana, a nie, że coś jest nie tak. Dostarczenie literału jest często jedynym, co akceptuje cel, a cała rodzina dołączeń istnieje właśnie po to. Ostrzeżenie mówi autorowi, która wartość idzie tą drogą i gdzie, aby wybór był widoczny, a nie ukryty; nie twierdzi, że ten wybór jest błędem.

Jest ostrzeżeniem, nigdy zatrzymaniem. Kompilacja kończy się powodzeniem i zapisuje swoje artefakty bez zmian. Organizacja, która chce, by poświadczenie dostarczane jako literał powodowało niepowodzenie kompilacji, wyraża to jako politykę zarządczą nad kompilacją, bo tam jest miejsce na odrzucenie — reguła, którą niektóre wdrożenia muszą łamać, nie jest domyślnym zachowaniem kompilatora.

Decyduje o nim okablowanie, nigdy wartość. Ostrzeżenie odczytuje wrażliwość zadeklarowaną przez schemat oraz dostarczanie zapisane przez autora. Żadna wartość nie jest sprawdzana, więc pole nigdy nie jest uznawane za poświadczenie na podstawie nazwy ani zawartości, a niezadeklarowana wartość, która akurat zawiera hasło, niczego nie wywołuje.

Dwa przypadki celowo pozostają bez ostrzeżenia. Klucz dostarczania, którego wskazywany klucz provides niczego nie publikuje, nie dostarcza literału i niczego nie zgłasza — ostrzeżenie dotyczy dostarczania, które nastąpiło. Natomiast slot, którego lista dozwolonych inject jest pusta, pozostawia dostarczanie encji Recipe, więc autor nie zapisał klucza dostarczania, który można by zgłosić, i nie ma nic do zrobienia.

Ostrzeżenie stanowi osobną klasę z własnym kodem, a --no-unsupported-field-warnings go nie wycisza: ta flaga obejmuje informacje o wierności celu, które są innym osądem, wyciszanym z innych powodów. Trafia ono też do edytora, gdzie pojawia się jako problem w encji Aggregate, gdy serwer języka działa z włączonym --build-on-inspect (lub kluczem konfiguracji serve.build_on_inspect). To ustawienie jest domyślnie wyłączone dla spójności z aggrega inspect: polecenie terminalowe podczas inspekcji grafu nigdy nie dochodzi do etapu renderowania, więc również nie zgłasza takiego ostrzeżenia, a inspekcja w edytorze, która także go nie zgłasza, pokazuje to samo co terminal. Włączenie ustawienia jest sposobem poproszenia edytora o dodatkową warstwę i nic nie jest wtedy zapisywane na dysku — etap jest wykonywany, a jego artefakty odrzucane. Dodaje ono ostrzeżenia zgłaszane przez kompilację podczas renderowania, ale żadnej z kontroli, na których kompilacja się zatrzymuje. Każdy opublikowany problem wskazuje warstwę, która go zgłosiła, więc edytor może odróżnić to ostrzeżenie od zgłaszanych przez etapy rozwiązywania i analizy.

Ostrzeżenie kompilacji dla wartości renderowanej przez mapowanie bez oznaczenia

Kompilacja wypisuje jedno ostrzeżenie na każdy liść values zadeklarowany jako wrażliwy, którego oznaczenia render nie może przenieść, podczas gdy autor wciąż ma nad tym kontrolę. Pojawia się ono przy renderze ze źródła source:, którego wartości są wynikiem mapowania valuesMapping — mapowania encji Recipe, dotyczącego liścia deklarowanego przez jej encję Component, albo mapowania encji FeatureRecipe należącej do encji Feature dołączonej do komponentu, dotyczącego liścia deklarowanego przez tę encję Feature. Klucze wyjściowe mapowania są jego własnym wymysłem, więc żadna deklaracja nie nazywa żadnego z nich, a cel nie otrzymuje dla liścia oznaczenia per klucz:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

Wiersz podaje liść pod jego współrzędną z definicji autora oraz encję Recipe lub FeatureRecipe, której mapowanie warunkuje to połączenie, ponieważ deklaracja i mapowanie są zapisane w dwóch różnych encjach; wiersz dołączenia zaczyna się od nazwy, pod którą je dołączono, dzięki czemu można odróżnić dwa dołączenia jednej encji Feature do jednego komponentu. Dźwignią jest usunięcie mapowania: bez niego wartości, które otrzymuje render źródła, mają klucze w postaci zadeklarowanych ścieżek liści, a oznaczenie przemieszcza się razem z nimi. Render wyłącznie artefaktów i render wyłącznie workloadu nie zgłaszają niczego, ponieważ nie przekazują celowi żadnej mapy wartości; podobnie encja Feature dołączona do granicy, która renderuje się względem pustego filaru values — powyższe ograniczenie jest tam trwałe, a ostrzeżenie nie wskazywałoby niczego do zrobienia. Podobnie jak ostrzeżenie dla wartości przekazywanej jako literał, jest to ostrzeżenie, a nigdy zatrzymanie, nie zmienia żadnego wyrenderowanego bajtu, stanowi osobną klasę z własnym kodem, sensitivity-not-conveyed, a --no-unsupported-field-warnings go nie wycisza. Jego pełny kształt opisuje strona Ostrzeżenia i wyniki lintera.

Gdzie deklaracja jest odczytywana, a gdzie nie

Słowo kluczowe jest odczytywane w węźle, w którym się znajduje, a odczyt podąża następnie każdą drogą, którą deklaracja może dotrzeć do tej danej: przez zagnieżdżone mapy właściwości, każdą gałąź kompozycji i cel $ref. Zarówno gałąź, jak i cel odwołania składają się na właściwość, która je zawiera, więc deklaracja znaleziona przez którekolwiek z nich jest zbierana dla tej właściwości; ścieżkę wydłuża tylko zejście przez properties.

Znacznik jest odczytywany niezależnie od tego, czy stoi obok jednego z tych słów kluczowych, czy wewnątrz tego, do czego słowo kluczowe sięga, więc dwa kształty nie wymagają celowego umieszczenia:

  • Obok $ref albo wewnątrz celu odwołania. Znacznik na odwołującym się liściu deklaruje ten liść. Znacznik w schemacie, do którego prowadzi odwołanie, również jest zbierany dla odwołującego się liścia, pod ścieżką tego liścia uzupełnioną o łańcuch poniżej niego — nigdy pod ścieżką wewnątrz definicji, gdzie nie ma żadnej wartości autora.
  • Obok słowa kluczowego kompozycji (allOf / anyOf / oneOf) albo wewnątrz własnych properties gałęzi. Gałąź składa się na obiekt, który ją zawiera, więc schodzi się do każdej gałęzi — łącznie z gałęziami warunkowymi węzła zapisanego jako JSON Schema — a deklaracja wewnątrz jednej z nich jest zbierana pod własną ścieżką składającej właściwości uzupełnioną o jej łańcuch.

Jeden kształt wymaga celowego umieszczenia znacznika:

  • Na samym liściu tablicy, a nie na typie jej elementu items. Tablicę, której elementy zawierają materiał, deklaruje się jako wrażliwą na poziomie tablicy, ponieważ typ elementu nie jest mapą właściwości i nie schodzi się do niego.

parameters: to inny słownik

sensitive nie należy do słownika typowanego kontraktu parameters:. Encja Aggregate, która deklaruje go we wpisie parametru, jest odrzucana podczas wczytywania encji Aggregate z diagnostyką koperty dokumentu zgłaszającą unexpected property: "sensitive", umiejscowioną na samym błędnym kluczu — tak samo jak każdy klucz spoza tego słownika, ponieważ kontrakt parametrów jest obiektem zamkniętym.

Ta asymetria jest zamierzona: oś wrażliwości obejmuje trzy filary danych deklarowane przez encję katalogu, a parametr jest wejściem kontraktu środowiska, a nie liściem filaru. Przenoszenie materiału uwierzytelniającego przez parametr opisano w architecture/08-credential-model.md, w części „Legacy charts that demand a formatted string”, która określa kompromis, na jaki idzie ta ścieżka.

Kompozycja za pomocą allOf, anyOf, oneOf

Słowa kluczowe kompozycji działają tak jak w JSON Schema:

# Inherit and extend
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, required: true }
username: { type: string, default: app_user }
password: { type: string, required: true }

Kompilator emituje te same słowa kluczowe kompozycji w rozwiązanym JSON Schema. Każdy z elementów kompozycji może być zapisany w formie kompaktowej, w JSON Schema albo jako odwołanie $ref:. Mieszanie tych form w obrębie jednej kompozycji jest obsługiwane.

Furtka — $jsonschema:

W przypadkach wykraczających poza słownictwo formy kompaktowej ($dynamicRef, unevaluatedProperties, głęboka kompozycja not:, typy rekurencyjne) dowolny węzeł może przejść na pełny JSON Schema:

values:
architecture: { type: string, enum: [standalone, replication] }
some_complex_field:
$jsonschema: |
type: object
unevaluatedProperties: false
allOf:
- $ref: "#/$defs/Foo"
- not:
required: [conflicting_field]
patternProperties:
"^x-": { type: string }
$defs:
Foo:
type: object
properties:
name: { type: string }

Blok $jsonschema: zawiera YAML w formacie JSON Schema; kompilator traktuje go jako przezroczyste przekazanie — treść trafia bezpośrednio do rozwiązanego dokumentu JSON Schema w miejscu danego węzła. Walidacja, raportowanie błędów i narzędzia działają na rozwiązanym dokumencie; furtka jest wyłącznie udogodnieniem przy tworzeniu.

Gałąź not: może zawierać description: wyjaśniający, dlaczego wykluczany przez nią kształt jest odrzucany. Wartość pasująca do tej gałęzi jest wtedy odrzucana z tym opisem jako powodem, wypisanym w jednym wierszu, zamiast ogólnego sformułowania „not allowed here (niedozwolone w tym miejscu)” — należy go więc pisać jako zdanie, które powinien przeczytać autor odrzuconej wartości. Używany jest tylko opis zapisany w samej gałęzi not:; opis we wpisie $defs, do którego gałąź jedynie się odwołuje, nie jest używany.

Każdy węzeł wewnątrz bloku jest odczytywany jako JSON Schema, a zapisane tam słowo kluczowe formy zwartej zachowuje swoje zwarte znaczenie (min: 3 przy łańcuchu nadal oznacza minimalną długość). $ref w bloku jest rozwiązywany tak samo jak poza nim: #/$defs/Foo wskazuje wpis w $defs: filaru, dlatego przykład deklaruje tam Foo, a odwołanie do wpisu, którego nikt nie zadeklarował, jest odrzucane podczas ładowania encji. $dynamicRef jest rozwiązywany względem $dynamicAnchor, więc można zapisać kształt rekurencyjny; wartość, która nie przechodzi walidacji głęboko w rekurencji, jest zgłaszana przy polu, które ją zawiera — tree.children w przypadku błędnego name dwa poziomy niżej w drzewie, którego elementy children to { $dynamicRef: "#node" }.

Dla unevaluatedProperties i unevaluatedItems obowiązuje jedno ograniczenie. Zapisane w węźle, który zawiera również odwołanie, słowo kluczowe kompozycji (allOf, anyOf, oneOf), warunek lub schemat zależny, każde z nich się ładuje, ale nie jest egzekwowane — a unevaluatedItems nie jest egzekwowane także obok contains. W powyższym przykładzie unevaluatedProperties: false stoi obok allOf, więc { name: n, extra: 1 } jest akceptowane, choć ani Foo, ani patternProperties nie deklaruje extra.

Furtka $jsonschema: działa na poziomie węzła, a nie dokumentu. Schemat może używać formy kompaktowej dla prostych części, furtki JSON Schema dla jednego złożonego pola i $ref: dla współdzielonych kształtów — wszystko w jednym dokumencie.

Łączenie formy kompaktowej i JSON Schema w jednym dokumencie

Formę kompaktową i JSON Schema można swobodnie łączyć na granicy dowolnego węzła. Reguła rozstrzygania zależy od kształtu treści:

  • Węzeł zawierający $jsonschema: jest traktowany jako JSON Schema (furtka).
  • Węzeł zawierający słowa kluczowe najwyższego poziomu w stylu JSON Schema (type:, properties:, additionalProperties:, if: itd.) jest traktowany jako JSON Schema (forma jawna).
  • Węzeł zawierający wyłącznie wpisy nazwa właściwości → schemat potomny (bez słów kluczowych zarezerwowanych przez JSON Schema) jest traktowany jako forma kompaktowa (forma wnioskowana).
  • Węzeł zawierający wyłącznie $ref: jest przekazywaną dalej referencją.
  • Węzeł z allOf: / anyOf: / oneOf: jest kompozycją; każdy wpis jest rozstrzygany niezależnie.

Dla liści w formie kompaktowej standardowym wzorcem jest field_name: { type: ..., constraints... } — mapa YAML zawierająca znane słownictwo formy kompaktowej. Mechanizm rozstrzygania rozpoznaje słowniki ograniczeń po ich kluczach.

W rzadkim niejednoznacznym przypadku (np. schemat w formie kompaktowej z polem dosłownie nazwanym type, które rozstrzyganie formy wnioskowanej zinterpretowałoby jako słowo kluczowe JSON Schema) kanonicznym rozwiązaniem jest forma jawna — zob. „Zarezerwowane słowa kluczowe w każdym zakresie formy wnioskowanej” powyżej.

Importowanie kontraktu z pliku — $import:

Kontrakt nie musi znajdować się wewnątrz encji, która go deklaruje. $import: wskazuje plik, z którego należy go odczytać:

spec:
schema:
$import: ./contracts/api-server.schema.yaml

Całe spec.schema pochodzi wtedy z tego pliku, który pisze się dokładnie tak jak zastępowany blok — filary na najwyższym poziomie, a pod nimi YAML w formie kompaktowej lub JSON Schema:

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

Pojedynczy filar można zaimportować osobno, a filary sąsiednie zapisać obok niego inline:

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

Ta sama forma działa w valueSchema: i infraSchema: gniazda usesSchema:.

Zasady, które nią rządzą:

  • $import: jest jedynym kluczem w miejscu, w którym występuje. Klucz sąsiedni zapisany obok niego jest odrzucany, zamiast pominięcia jednego z nich.
  • Ścieżka względna jest rozwiązywana względem katalogu zawierającego plik encji, która ją zadeklarowała, nigdy względem katalogu, z którego uruchamiana jest kompilacja — to ta sama baza, której używają valuesMapping:, workload: i artifacts:. Musi pozostać wewnątrz tego katalogu, ponieważ każdy plik, który zawiera publikacja encji, jest pobierany właśnie stamtąd: ścieżka wychodząca poza niego lub ścieżka bezwzględna wskazuje plik, który nie zostałby przeniesiony razem z encją, i jest odrzucana — zob. A path names content outside the entity’s own directory (Ścieżka wskazuje treść poza własnym katalogiem encji). Schemat współdzielony przez kilka encji należy umieścić w SchemaLibrary i odwoływać się do niego przez $ref:.
  • Importowany plik jest przenoszony razem z encją. Opublikowana encja zawiera każdy plik importowany przez jej schemat, łącznie z każdym plikiem łańcucha, dzięki czemu kopia pobrana z rejestru odczytuje ten sam kontrakt i waliduje zapisane względem niego wartości — zob. aggrega push.
  • Importowany plik zawiera treść schematu, a nie dokument encji. Plik, którego treść nie jest mapą YAML, jest odrzucany z podaniem nazwy pliku.
  • Importowany plik może sam być pojedynczym $import:, który jest rozwiązywany rekurencyjnie; łańcuch wracający do pliku, który jest już odczytywany, jest odrzucany z podaniem łańcucha.

Import jest odczytywany podczas ładowania encji, więc każde miejsce odczytujące tę encję widzi ten sam kontrakt: aggrega validate, kompilacja, aggrega push, aggrega inspect i edytor. Plik, którego nie można odczytać, lub treść niebędąca schematem są odrzucane w tym momencie, zamiast pozostawiać kontrakt niewymuszony — a push odrzuca je, zanim cokolwiek zostanie opublikowane.

$import: i $ref: nie są wymienne. $import: wskazuje plik i zastępuje całą treść; $ref: wskazuje wpis SchemaLibrary po tożsamości i składa się w dowolnym węźle. Wartość $import: zawierająca tożsamość biblioteki lub host rejestru jest odrzucana ze wskazówką, by użyć $ref:. Zob. cross-document-ref.md.

Przestrzeń nazw rozszerzeń Aggrega — x-aggrega-*

Forma zwarta rozpoznaje każde słowo kluczowe z prefiksem x-aggrega- jako rozszerzenie specyficzne dla Aggrega. Przestrzeń nazw jest otwarta: nowe adnotacje trafiają do katalogu bez zmian w słowniku dla poszczególnych słów kluczowych. Autorzy piszący x-aggrega-selector, x-aggrega-narrowed-from lub przyszłe adnotacje umieszczają ich treść we właściwym zakresie w rozwiązanym JSON Schema bez odrzucenia w czasie kompilacji.

Prefiks przestrzeni nazw ma znaczenie: literówka taka jak x-agrega-source (brak jednego g) NIE jest rozpoznawana jako słowo kluczowe rozszerzenia i zostałaby odrzucona przez semantykę zamkniętych obiektów w zakresach formy wnioskowanej. Zakres prefiksu działa jak sieć wykrywająca literówki w powierzchni adnotacji katalogu.

Konkretne adnotacje x-aggrega-* są emitowane przez kompilator w dobrze znanych punktach potoku:

  • x-aggrega-selector: — emitowane przez syntezę usesSchema: i featuresSchema:, aby przenieść ciąg selektora wskazujący zgodne komponenty dostawcy (Components).
  • x-aggrega-sensitive: — emitowane przez liść deklarujący sensitive: true. Zobacz Deklarowanie liścia jako wrażliwego powyżej.

Autorzy katalogów piszący własne słowa kluczowe rozszerzeń używają tej samej przestrzeni nazw; narzędzia niższego rzędu, które konsumują skompilowany JSON Schema, odczytują klucze x-aggrega-* bez kolizji z przestrzenią słów kluczowych samego JSON Schema.

Przykład praktyczny — schemat encji Component dla MariaDB

Reprezentatywny schemat encji Component w formie zwartej dla magazynu danych MariaDB, pokazujący formę wnioskowaną w całym dokumencie, mieszane ograniczenia liści, odwołania, warunkowy kształt oraz praktyczny przykład oneOf dla bloku uwierzytelniania:

spec:
schema:
values:
architecture:
type: string
enum: [standalone, replication]
default: standalone
description: |
Topology mode. `standalone` runs a single primary; `replication` runs a primary
plus N secondary replicas governed by the secondary block.
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary:
when: '{{ eq $.architecture "replication" }}'
properties:
replicaCount: { type: integer, min: 2, max: 8, default: 2 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, sensitive: true, required: true }
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics:
enabled: { type: boolean, default: false }
serviceMonitor:
enabled: { type: boolean, default: false }
namespace: { type: string }
labels: { type: object, valuesType: string }
$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec:
size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true }
storageClass: { type: string }

Zapisany jako YAML w JSON Schema ten sam kontrakt wypisuje dla każdego obiektu type: object, properties: i additionalProperties: false oraz ponownie wymienia każde wymagane pole w required: rodzica, więc jest znacznie dłuższy. Zysk ze zwartości narasta w większych kontraktach Component i jest na tyle istotny, że forma zwarta jest domyślną formą tworzenia dla schema:, parameters: oraz wpisów SchemaLibrary.

Odsyłacze

  • Semantyka rozwiązywania $ref: między dokumentami (składnia required: obok odwołania między dokumentami; rozwijanie łańcuchów biblioteka–biblioteka; konsument zawęża bibliotekę): cross-document-ref.md.
  • Gramatyka tworzenia bloku assertions: (reguły obejmujące wiele pól, których nie da się wyrazić za pomocą validate: w formie kompaktowej): templates/assertions-block.md.
  • Zestaw filarów danych, w których osadzone są schematy w formie kompaktowej (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Reguły rozwijania skróconych URI OCI (domyślna domena, segment rejestru, wersja zastępcza, rozwijanie wydawcy): uri-grammar.md.
  • Tworzenie encji SchemaLibrary (miejsce w katalogu, w którym znajdują się schematy, do których można się odwołać przez $ref:): ../entities/schemalibrary.md.