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

Rozwiązywanie odwołań `$ref:` między dokumentami

Ta strona opisuje semantykę rozwiązywania odwołań $ref: między dokumentami w warstwie tworzenia schematów w Aggrega — co widzą autorzy encji Components, Features i wpisów SchemaLibrary, gdy $ref: przekracza granicę dokumentu i sięga do biblioteki — oraz reguły required: dla poszczególnych składni, które określają, które formy zapisu działają poprawnie z rozwijaniem odwołań między dokumentami.

$ref: jest natywnym elementem JSON Schema 2020-12. Występuje w treści schema: (wpisy Component, Feature, SchemaLibrary), w schematach w formie zwartej oraz w syntetyzowanej warstwie JSON Schema, którą emitują usesSchema: i featuresSchema:. Ta strona skupia się na przypadku między dokumentami, w którym $ref: wskazuje wpis SchemaLibrary w osobnym pliku lub artefakcie OCI.

Dziedziczenie encji katalogowych (Component rozszerzający Component) opisano w inheritance-and-interface.md. Release rozszerzający Release to inny mechanizm, działający na dokumencie, który nie jest indeksowany w katalogu; opisano go w entities/release.md.

$import: to drugie słowo kluczowe sięgające do treści spoza dokumentu, a oba odpowiadają na różne pytania. $ref: wskazuje wpis w SchemaLibrary według tożsamości — rozwiązuje go katalog, a wersję dostarcza plik blokady — i można go składać w dowolnym węźle. $import: wskazuje plik obok encji i zastępuje całą treść zawartością tego pliku. $import: działa w warstwie schematów, a także w valuesMapping:, workload:, artifacts: i parameters:; informacje o $import: w schemacie można znaleźć w compact-form-authoring.md, §„Importing a contract from a file”.

Semantyka rozwiązywania $ref:

$ref: stosuje standardowe rozwiązywanie JSON Schema 2020-12. W praktyce występują następujące kształty referencji:

  • Lokalne fragmenty w obrębie tego samego dokumentu: { $ref: "#/$defs/PodResources" } — rozwiązuje się do wpisu PodResources w $defs schematu.
  • Referencje do wpisów SchemaLibrary według tożsamości: { $ref: "WebPrimitives#/schemas/URL" } — forma z samą nazwą <Library>#/schemas/<Entry>. Nazwa biblioteki jest rozwiązywana względem rozwiązanego katalogu, a fragment JSON Pointer #/schemas/<Entry> wybiera wpis; wersję dostarcza plik blokady (lockfile), a nie referencja. Referencja nie zawiera hosta rejestru — forma z hostem oci://<host>/… jest odrzucana podczas kompilacji z diagnostyką, która kieruje autora do formy z tożsamością, dzięki czemu fizyczna lokalizacja rejestru nigdy nie trafia do tworzonego źródła. To, skąd serwowane są bajty biblioteki (z lokalnego katalogu, z pamięci podręcznej treści lub ze zdalnego rejestru), jest sprawą resolvera, wiązaną w czasie rozwiązywania, i nigdy nie jest częścią referencji.
  • Ścieżka pliku nie jest celem referencji: { $ref: "./schemas/foo.yaml#/definitions/Foo" } jest odrzucana podczas kompilacji schematu z diagnostyką wskazującą formę <Library>#/schemas/<Entry>. Treść schematu przechowywaną w pliku obok encji dołącza się zamiast tego za pomocą $import:, ograniczonego do własnego katalogu encji, jak każdy plik odczytywany przez encję.

Referencja jest rozwiązywana w czasie kompilacji. Ekspander wstawia przywoływaną treść bezpośrednio do schematu konsumenta; wyrenderowane IR zawiera wstawioną treść, a nie pośrednie odwołanie.

$ref: w naturalny sposób łączy się ze słowami kluczowymi kompozycji JSON Schema:

secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
- description: "Replication-mode secondary instances."

allOf łączy przywoływany kształt NodePool z dodatkowymi ograniczeniami.

Składnia required: przy międzydokumentowym $ref:

Autorzy katalogów, deklarując wymagane właściwości w encji Component lub Feature, wybierają między dwoma kształtami zapisu: znacznikami na poziomie liści (required: true przy każdej właściwości) albo tablicą na poziomie rodzica (required: [name1, name2, ...] w zakresie obiektu). Oba kształty są poprawne w JSON Schema 2020-12 i oba są uwzględniane przy międzydokumentowym rozwijaniu $ref:, jeśli zapisano je tam, gdzie pokazuje ta sekcja.

Zapis w formie wnioskowanej bez $ref: — znaczniki na poziomie liści są gromadzone w czasie kompilacji. Kompilator przechodzi przez każdą właściwość i tam, gdzie liść ma required: true, dodaje nazwę właściwości do tablicy required: syntetyzowanego rodzica.

spec:
schema:
values:
database: { type: string, required: true }
display_name: { type: string, required: true }
default_locale: { type: string, default: "en-US" }

Kompilator emituje required: [database, display_name] w zakresie rodzica.

Konsumenci zawierający $ref: — obok międzydokumentowego $ref: można zapisać tylko properties, required i description, a wymagania dodawane przez konsumenta to te, które tam zapisuje: tablica required: na poziomie rodzica albo znacznik required: true na poziomie liścia przy właściwości deklarowanej pod properties:. Własne wymagania wskazywanego wpisu — znaczniki na poziomie liści w jego formie wnioskowanej lub jego własna tablica required: — obowiązują przez odwołanie bez zmian. Tablica na poziomie rodzica wymienia wymagania bez ponownego deklarowania właściwości, które wpis już deklaruje:

spec:
schema:
values:
$ref: "Datastores#/schemas/PostgresPayload"
required: [database, display_name]

Znacznik na poziomie liścia również jest uwzględniany — przy właściwości, którą konsument deklaruje obok odwołania — więc zapisane tam properties: { database: { type: string, required: true } } czyni database wymaganym dokładnie tak samo jak required: [database]. Właściwość konsumenta zastępuje właściwość wpisu o tej samej nazwie (zob. Konsument zawęża wpis biblioteki), dlatego należy zadeklarować ją ponownie w zamierzonym kształcie.

Rozwijanie łańcuchów między bibliotekami

Wpis SchemaLibrary może sam zawierać $ref: wskazujący na wpis innej SchemaLibrary, tworząc łańcuch. Kompilator przechodzi łańcuch w czasie kompilacji: każdy $ref: napotkany podczas rozwijania wpisu jest sam rozwijany w kategoriach biblioteki, która go zawiera.

# Library A
spec:
schemas:
DatabasePayload:
type: object
properties:
host: { type: string }
credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)
spec:
schemas:
BasicAuth:
type: object
properties:
username: { type: string }
password: { type: string }

Konsumencka encja Component, która odwołuje się do DatabasePayload, otrzymuje w pełni rozwinięty kształt, w którym credentials jest wypełnione na podstawie wpisu BasicAuth z biblioteki B. Wartość naruszająca ograniczenie wniesione przez łańcuch jest odrzucana na jej własnej ścieżce w sprawdzanym dokumencie, a odrzucenie nie wskazuje wpisu biblioteki, z którego pochodzi ograniczenie; aby go znaleźć, należy prześledzić łańcuch $ref: od konsumenta.

Konsument zawęża wpis biblioteki

Konsumencka encja Component może zadeklarować właściwość, której nazwa pokrywa się z nazwą właściwości pobranej z wpisu biblioteki. W takim przypadku skompilowana właściwość konsumenta całkowicie zastępuje właściwość wpisu biblioteki w scalonym kształcie.

# Library entry
spec:
schemas:
ToolContract:
type: object
properties:
side_effects:
type: array
items: { type: string, enum: [read, write, delete] }
# Consumer Component
spec:
schema:
values:
$ref: "Tools#/schemas/ToolContract"
properties:
side_effects:
type: array
items: { type: string, enum: [read] }
default: [read]

W scalonym kształcie side_effects odzwierciedla węższy kontrakt konsumenta (enum: [read], z wartością default); szersze enum: [read, write, delete] wpisu biblioteki znika. Właściwość jest autorstwa konsumenta.

Jest to oczekiwane zachowanie: doprecyzowywanie przez konsumentów właściwości wpisu biblioteki to kanoniczny wzorzec zawężania. Zawężanie odbywa się bez śladu: właściwość konsumenta ma własne, niezależne pochodzenie.

Odsyłacze

  • Dziedziczenie encji katalogowych (Component-extends-Component, Feature-extends-Feature) opisano w inheritance-and-interface.md.
  • Dziedziczenie między dokumentami po stronie wdrożenia, których odwołania wskazują pliki, a nie encje katalogowe: rozszerzanie encji Release przez Release opisano w entities/release.md, a rozszerzanie encji Manifest przez Manifest w entities/manifest.md.
  • Wskaźniki źródła specyficzne dla dostawcy (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:) opisuje dokumentacja encji Recipe. Wskaźniki źródła Provider nie są ujednolicone pod $ref:; plugin dostawcy konsumuje je bezpośrednio.
  • Reguły rozwijania skróconych URI OCI (domyślna domena, kontekstowe rozwijanie encji, pierwszeństwo rozstrzygania, obsługa wersji) opisano w uri-grammar.md.