Resolusi `$ref:` lintas dokumen
Halaman ini mendokumentasikan semantik resolusi referensi $ref: lintas dokumen dalam permukaan penulisan skema Aggrega — apa yang dilihat oleh penulis Components, Features, dan entri SchemaLibrary ketika sebuah $ref: melintasi batas dokumen ke dalam sebuah pustaka, serta aturan required: per sintaksis yang menetapkan bentuk penulisan mana yang bekerja dengan baik bersama ekspansi lintas dokumen.
$ref: merupakan fitur bawaan JSON Schema 2020-12. Ia muncul di dalam konten schema: (entri Component, Feature, SchemaLibrary), di dalam skema bentuk ringkas, dan di dalam lapisan JSON Schema hasil sintesis yang dihasilkan oleh usesSchema: dan featuresSchema:. Halaman ini berfokus pada kasus lintas dokumen, ketika $ref: menargetkan entri SchemaLibrary dalam berkas atau artefak OCI yang terpisah.
Untuk pewarisan entitas katalog (Component-extends-Component), lihat inheritance-and-interface.md. Release yang memperluas Release adalah mekanisme yang berbeda atas dokumen yang tidak diindeks katalog; hal ini didokumentasikan di entities/release.md.
$import: adalah kata kunci lain yang menjangkau konten di luar dokumen, dan keduanya menjawab pertanyaan yang berbeda. $ref: menamai sebuah entri dalam SchemaLibrary berdasarkan identitas — katalog meresolusikannya, lockfile menyediakan versinya — dan dapat dikomposisikan di simpul mana pun. $import: menamai sebuah berkas di samping entitas dan mengganti seluruh konten dengan isi berkas tersebut. $import: berlaku pada permukaan skema serta pada valuesMapping:, workload:, artifacts: dan parameters:; untuk $import: pada skema, lihat compact-form-authoring.md §“Mengimpor kontrak dari berkas”.
Semantik resolusi $ref:
$ref: mengikuti resolusi standar JSON Schema 2020-12. Bentuk referensi berikut muncul dalam praktik:
- Fragmen lokal di dalam dokumen yang sama:
{ $ref: "#/$defs/PodResources" }— di-resolve ke entriPodResourcesdi bawah$defsmilik skema. - Referensi entri SchemaLibrary berdasarkan identitas:
{ $ref: "WebPrimitives#/schemas/URL" }— bentuk nama polos<Library>#/schemas/<Entry>. Nama pustaka di-resolve terhadap katalog yang telah di-resolve, dan fragmen JSON Pointer#/schemas/<Entry>memilih entrinya; versinya disediakan oleh lockfile, bukan oleh referensi. Sebuah referensi tidak membawa host registry — bentuk yang memuat hostoci://<host>/…ditolak saat kompilasi dengan diagnostik yang mengarahkan penulis ke bentuk identitas, sehingga lokasi registry fisik tidak pernah masuk ke sumber yang ditulis. Dari mana byte pustaka disajikan (direktori katalog lokal, cache konten, atau registry jarak jauh) adalah urusan resolver, ditetapkan pada saat resolusi, dan tidak pernah menjadi bagian dari referensi. - Path file bukan target referensi:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }ditolak saat skema dikompilasi, dengan diagnostik yang menyebutkan bentuk<Library>#/schemas/<Entry>. Konten skema yang disimpan dalam file di samping entitas dibawa masuk dengan$import:sebagai gantinya, yang dibatasi oleh direktori entitas itu sendiri seperti setiap file yang dibaca oleh entitas.
Referensi di-resolve pada waktu kompilasi. Expander menyisipkan konten yang direferensikan ke dalam skema konsumen; IR yang dirender membawa konten yang disisipkan, bukan indireksinya.
$ref: dapat dikomposisikan secara alami dengan kata kunci komposisi JSON Schema:
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."allOf mengomposisikan bentuk NodePool yang direferensikan dengan batasan tambahan.
Sintaks required: di bawah $ref: lintas dokumen
Penulis katalog memilih antara dua bentuk penulisan saat mendeklarasikan properti wajib pada Component atau Feature: penanda tingkat daun (required: true pada setiap properti) atau larik tingkat induk (required: [name1, name2, ...] pada cakupan objek). Kedua bentuk tersebut valid dalam JSON Schema 2020-12, dan keduanya diperhitungkan dalam ekspansi $ref: lintas dokumen, jika ditulis di tempat yang ditunjukkan bagian ini.
Penulisan bentuk tersimpulkan tanpa $ref: — penanda tingkat daun terakumulasi pada waktu kompilasi. Compiler menelusuri setiap properti dan, jika sebuah daun membawa required: true, menambahkan nama properti tersebut ke larik required: milik induk yang disintesis.
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }Compiler menghasilkan required: [database, display_name] pada cakupan induk.
Konsumen yang memuat $ref: — di samping $ref: lintas dokumen hanya properties, required, dan description yang boleh ditulis, dan field wajib yang ditambahkan konsumen adalah yang ditulisnya di sana: larik required: di tingkat induk, atau penanda required: true tingkat leaf pada properti yang dideklarasikannya di bawah properties:. Field wajib milik entri yang dirujuk — penanda tingkat leaf dalam bentuk tersiratnya, atau larik required: miliknya sendiri — berlaku melalui referensi tanpa perubahan. Larik tingkat induk menyebutkan field wajib tanpa mendeklarasikan ulang properti yang sudah dideklarasikan entri:
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]Penanda tingkat leaf juga diperhitungkan, pada properti yang dideklarasikan konsumen di samping referensi — sehingga properties: { database: { type: string, required: true } } yang ditulis di sana menjadikan database wajib persis seperti required: [database]. Properti konsumen menggantikan properti entri yang bernama sama (lihat Konsumen mempersempit entri pustaka), jadi deklarasikan ulang dengan bentuk yang Anda maksudkan.
Ekspansi rantai dari pustaka ke pustaka
Sebuah entri SchemaLibrary dapat berisi $ref: yang menunjuk ke entri SchemaLibrary lain, sehingga membentuk rantai. Kompiler menelusuri rantai tersebut pada waktu kompilasi: setiap $ref: yang ditemui saat sebuah entri diekspansi juga diekspansi, dalam konteks pustaka yang memuatnya.
# 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 }Sebuah Component konsumen yang mereferensikan DatabasePayload menerima bentuk yang sepenuhnya diekspansi, dengan credentials diisi dari BasicAuth milik pustaka B. Nilai yang melanggar batasan yang disumbangkan oleh rantai tersebut ditolak pada path-nya sendiri di dokumen yang sedang diperiksa, dan penolakan itu tidak menyebutkan entri pustaka asal batasan tersebut; telusuri rantai $ref: dari konsumen untuk menemukannya.
Konsumen mempersempit entri pustaka
Sebuah Component konsumen dapat mendeklarasikan properti yang namanya cocok dengan properti yang ditarik dari entri pustaka. Jika hal ini terjadi, properti hasil kompilasi milik konsumen sepenuhnya menggantikan properti entri pustaka dalam bentuk gabungan.
# 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]Dalam bentuk gabungan, side_effects mencerminkan kontrak konsumen yang lebih sempit (enum: [read], dengan sebuah default); enum: [read, write, delete] yang lebih luas milik entri pustaka tidak ada lagi. Properti tersebut ditulis oleh konsumen.
Ini adalah perilaku yang diharapkan: konsumen yang menyempurnakan properti entri pustaka merupakan pola penyempitan yang kanonis. Penyempitan terjadi tanpa pemberitahuan: properti konsumen berdiri di atas asal-usulnya sendiri.
Rujukan silang
- Untuk pewarisan entitas katalog (Component-extends-Component, Feature-extends-Feature), lihat inheritance-and-interface.md.
- Untuk pewarisan antar dokumen sisi deployment, yang referensinya menamai file alih-alih entitas katalog: Release yang memperluas Release didokumentasikan di
entities/release.md, dan Manifest yang memperluas Manifest dientities/manifest.md. - Untuk penunjuk sumber khusus penyedia (
Recipe.spec.source.chart:,Recipe.spec.source.modulePath:), lihat dokumentasi Recipe per entitas. Penunjuk sumber Provider tidak disatukan di bawah$ref:; plugin penyedia mengonsumsinya secara langsung. - Untuk aturan ekspansi singkatan URI OCI (domain default, ekspansi entitas kontekstual, prioritas resolusi, penanganan versi), lihat uri-grammar.md.