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 wpisuPodResourcesw$defsschematu. - 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 hostemoci://<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 Aspec: 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 entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: 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 wentities/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.