Belgeler arası `$ref:` çözümlemesi
Bu sayfa, Aggrega’nın şema yazım yüzeyindeki belgeler arası $ref: başvurularının çözümleme semantiğini belgeler: bir $ref: belge sınırını aşarak bir kütüphaneye geçtiğinde Components, Features ve SchemaLibrary girdilerinin yazarlarının ne gördüğünü ve hangi yazım biçimlerinin belgeler arası genişletmeyle sorunsuz çalıştığını belirleyen, sözdizimine göre required: kurallarını.
$ref:, JSON Schema 2020-12’nin kendi öğesidir. schema: içeriğinde (Component, Feature, SchemaLibrary girdileri), kompakt biçimli şemalarda ve usesSchema: ile featuresSchema: öğelerinin ürettiği sentezlenmiş JSON Schema katmanında yer alır. Bu sayfa, $ref: öğesinin ayrı bir dosyadaki veya OCI yapıtındaki bir SchemaLibrary girdisini hedeflediği belgeler arası duruma odaklanır.
Katalog varlığı kalıtımı (Component’in Component’i genişletmesi) için bkz. inheritance-and-interface.md. Bir Release’in bir Release’i genişletmesi, katalogda dizinlenmeyen bir belge üzerinde işleyen farklı bir mekanizmadır; entities/release.md sayfasında belgelenmiştir.
$import:, belgenin dışındaki içeriğe ulaşan diğer anahtar sözcüktür ve ikisi farklı sorulara yanıt verir. $ref:, bir SchemaLibrary girdisini kimliğiyle adlandırır (katalog onu çözümler, kilit dosyası sürümü sağlar) ve herhangi bir düğümde birleşir. $import: ise varlığın yanındaki bir dosyayı adlandırır ve içeriğin tamamını o dosyanın içerdikleriyle değiştirir. $import:, şema yüzeyinde olduğu gibi valuesMapping:, workload:, artifacts: ve parameters: konumlarında da uygulanır; bir şemada $import: için bkz. compact-form-authoring.md §“Importing a contract from a file”.
$ref: çözümleme anlamları
$ref:, JSON Schema 2020-12 standart çözümlemesini izler. Uygulamada şu başvuru biçimleri görülür:
- Aynı belge içindeki yerel parçalar:
{ $ref: "#/$defs/PodResources" }— şemanın$defsaltındakiPodResourcesgirdisine çözümlenir. - Kimliğe göre SchemaLibrary girdisi başvuruları:
{ $ref: "WebPrimitives#/schemas/URL" }— yalın adlı<Library>#/schemas/<Entry>biçimi. Kitaplık adı çözümlenmiş kataloğa karşı çözümlenir ve#/schemas/<Entry>JSON Pointer parçası girdiyi seçer; sürümü başvuru değil, kilit dosyası sağlar. Bir başvuru kayıt defteri ana bilgisayarı taşımaz — ana bilgisayar içerenoci://<host>/…biçimi derleme sırasında, yazarı kimlik biçimine yönlendiren bir tanılamayla reddedilir; böylece fiziksel bir kayıt defteri konumu hiçbir zaman yazılan kaynağa girmez. Kitaplığın baytlarının nereden sunulduğu (yerel bir katalog dizini, içerik önbelleği ya da uzak bir kayıt defteri) çözümleyicinin işidir, çözümleme zamanında bağlanır ve hiçbir zaman başvurunun parçası değildir. - Dosya yolu bir başvuru hedefi değildir:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }, şema derlenirken<Library>#/schemas/<Entry>biçimini belirten bir tanılamayla reddedilir. Varlığın yanındaki bir dosyada tutulan şema içeriği bunun yerine$import:ile getirilir; bu da bir varlığın okuduğu her dosya gibi varlığın kendi diziniyle sınırlıdır.
Başvuru derleme zamanında çözümlenir. Genişletici, başvurulan içeriği tüketicinin şemasına satır içi yerleştirir; işlenen IR dolaylamayı değil, satır içi yerleştirilmiş içeriği taşır.
$ref:, JSON Schema’nın birleştirme anahtar sözcükleriyle doğal biçimde birleşir:
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."allOf, başvurulan NodePool biçimini ek kısıtlamalarla birleştirir.
Belgeler arası $ref: altında required: sözdizimi
Katalog yazarları, bir Component veya Feature üzerinde zorunlu özellikleri bildirirken iki yazım biçimi arasında seçim yapar: yaprak düzeyindeki işaretler (her özellikte required: true) ya da üst düzeydeki dizi (nesne kapsamında required: [name1, name2, ...]). Her iki biçim de JSON Schema 2020-12’de geçerlidir ve bu bölümün gösterdiği yere yazıldığında her ikisi de belgeler arası $ref: genişletmesi altında dikkate alınır.
$ref: olmadan çıkarımsal biçimde yazım — yaprak düzeyindeki işaretler derleme zamanında biriktirilir. Derleyici her özelliği dolaşır ve bir yaprak required: true taşıdığında özellik adını sentezlenen üst öğenin required: dizisine ekler.
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }Derleyici, üst kapsamda required: [database, display_name] üretir.
$ref: taşıyan tüketiciler — belgeler arası bir $ref: anahtarının yanına yalnızca properties, required ve description yazılabilir ve tüketicinin eklediği zorunluluklar orada yazdıklarıdır: üst düzeyde bir required: dizisi ya da properties: altında bildirdiği bir özellikteki yaprak düzeyinde required: true işareti. Başvurulan girdinin kendi zorunlulukları — çıkarımlı biçimindeki yaprak düzeyi işaretler ya da kendine ait bir required: dizisi — başvuru aracılığıyla değişmeden uygulanır. Üst düzeydeki bir dizi, girdinin zaten bildirdiği özellikleri yeniden bildirmeden zorunlulukları adlandırır:
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]Yaprak düzeyindeki bir işaret de, tüketicinin başvurunun yanında bildirdiği bir özellikte geçerlidir — dolayısıyla oraya yazılan properties: { database: { type: string, required: true } }, database alanını tam olarak required: [database] gibi zorunlu kılar. Tüketicinin özelliği, girdinin aynı adlı özelliğinin yerini alır (bkz. Tüketici kütüphane girdisini daraltır); bu yüzden onu kastettiğiniz yapıyla yeniden bildirin.
Kütüphaneden kütüphaneye zincir genişletme
Bir SchemaLibrary girdisi, başka bir SchemaLibrary girdisini gösteren bir $ref: içerebilir ve böylece bir zincir oluşur. Derleyici zinciri derleme zamanında dolaşır: bir girdi genişletilirken karşılaşılan her $ref: de, onu barındıran kütüphanenin terimleriyle genişletilir.
# 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 }DatabasePayload’a başvuran tüketici bir Component, credentials alanı B kütüphanesinin BasicAuth girdisinden doldurulmuş, tamamen genişletilmiş şekli alır. Zincirin katkıda bulunduğu bir kısıtlamayı ihlal eden bir değer, denetlenen belgede kendi yolunda reddedilir ve ret, kısıtlamanın geldiği kütüphane girdisini adlandırmaz; onu bulmak için tüketiciden başlayarak $ref: zincirini izleyin.
Tüketici, kütüphane girdisini daraltır
Tüketici bir Component, adı bir kütüphane girdisinden alınan bir özelliğin adıyla eşleşen bir özellik bildirebilir. Bu durumda, birleştirilmiş şekilde tüketicinin derlenmiş özelliği kütüphane girdisininkinin tamamen yerini alır.
# 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]Birleştirilmiş şekilde side_effects, tüketicinin daha dar sözleşmesini (enum: [read], bir default ile birlikte) yansıtır; kütüphane girdisinin daha geniş enum: [read, write, delete] tanımı ortadan kalkar. Özellik tüketici tarafından yazılmıştır.
Beklenen davranış budur: tüketicilerin bir kütüphane girdisinin özelliğini inceltmesi, standart daraltma örüntüsüdür. Daraltma sessizdir: tüketicinin özelliği kendi kökenine dayanır.
Çapraz bağlantılar
- Katalog varlığı kalıtımı (Component-extends-Component, Feature-extends-Feature) için inheritance-and-interface.md sayfasına bakın.
- Başvuruları katalog varlıklarını değil dosyaları adlandıran dağıtım tarafı belgeleri arasındaki kalıtım için: bir Release’i genişleten bir Release
entities/release.mdsayfasında, bir Manifest’i genişleten bir Manifest iseentities/manifest.mdsayfasında belgelenmiştir. - Sağlayıcıya özgü kaynak işaretçileri (
Recipe.spec.source.chart:,Recipe.spec.source.modulePath:) için varlık başına Recipe belgelerine bakın. Provider kaynak işaretçileri$ref:altında birleştirilmez; bunları doğrudan sağlayıcı eklentisi tüketir. - OCI URI kısaltması genişletme kuralları (varsayılan alan adı, bağlama göre varlık genişletme, çözümleme önceliği, sürüm işleme) için uri-grammar.md sayfasına bakın.