Konteks templat parameters
Pilar parameters: membawa nilai parameter yang dipenuhi oleh Release dan divalidasi oleh kontrak. Dua model mental paralel mengatur aksesibilitasnya:
- Permukaan templat nilai (string
values:komponen / fitur / sub-aggregate di dalam Aggregate, ditambahvaluesMappingpada Recipe,injectMappingdanprovidespada FeatureRecipe, serta badan Workload) mengonsumsi nilai parameter sebagai literal yang sudah diinterpolasi. Tahap interpolasi di dalam resolusi mengevaluasi seluruh teks Aggregate sebagai templat dan mengganti setiap referensi{{ .parameters.<slot> }}dengan nilai yang telah diresolusi; permukaan templat nilai di hilir tidak pernah melihat.parameterssecara langsung dalam konteks templat mereka. - Permukaan templat path (templat
directory:dansubDirectory:yang ditulis operator pada batas Release) membaca.parameters.<slot>secara langsung saat evaluasi templat path selama rendering. Peta parameter gabungan tetap dapat dibaca hingga akhir rendering sehingga templat path dapat membaca.parametersterhadap daftar izin tertutup.
Pemberian akses yang asimetris — templat path membaca .parameters secara langsung; templat nilai tidak — membuat setiap lapisan memiliki apa yang dibutuhkannya: values: di sisi pengembang meneruskan data spesifik lingkungan yang sudah diresolusi ke templat nilai; templat path di sisi operator mereferensikan parameter region / lingkungan / account-id tanpa harus bolak-balik melalui skema values milik Aggregate.
Halaman ini mendokumentasikan tahap interpolasi, bentuk nilai per slot, pola akses di dalam string YAML Aggregate, pengecualian templat path, dan berapa lama peta gabungan tetap dapat dibaca. Untuk bentuk konteks templat Recipe / FeatureRecipe yang lebih luas (.values, .infra, .uses, dll.), lihat template-context-contract.md. Untuk ketersediaan per lokasi templat di sepanjang pipeline kompilasi, lihat expansion-matrix.md. Untuk bentuk deklarasi kontrak parameter bertipe pada Aggregate, lihat entities/aggregate.md §“Typed parameter contracts”. Untuk daftar izin variabel templat path yang menyertakan .parameters.<slot> pada evaluasi directory: / subDirectory: di batas, lihat path-template-variables.md.
Siklus hidup parameter
Compiler me-resolve parameter dalam empat fase berurutan:
- Pembacaan kontrak — blok
spec.parameters:milik Aggregate diperiksa berdasarkan ketentuannya sendiri sebelum nilai Release mana pun dilihat, sehingga slot yang tidak dapat membatasi apa pun menghentikan build meskipun tidak ada Release yang menyediakannya.minLengthataumaxLengthbernilai negatif pada deklarasi parameter itu sendiri ditolak saat Aggregate dimuat, dengan menyebutkan nama parameter dan kuncinya. Setiappattern— pada slot itu sendiri maupun di dalam kontrak bersarang mana pun di bawahitems,propertiesatauvaluesType— dikompilasi sebagai ekspresi reguler, dan pola yang tidak dapat dikompilasi ditolak dengan menyebutkan parameter, pola, dan alasannya. Batas panjang di dalam kontrak bersarang tidak terikat pada batas bawah tersebut; lihatentities/aggregate.md. - Pengisian default — slot yang memiliki
default:dan tidak menerima nilai dari Release akan diisi dengan nilai default-nya. Map.parametersberada dalam cakupan pada titik ini. - Validasi kontrak parameter — setiap nilai dalam map gabungan, baik yang disediakan oleh Release maupun yang diisi oleh
default:, divalidasi terhadap batasantype/enum/min/max/pattern/ struktur bersarang yang dideklarasikan padaspec.parameters.<slot>milik Aggregate; sebuahpatterndicocokkan dengan ekspresi yang dikompilasi saat kontrak dibaca. Map.parametersada dalam konteks in-memory validator sebagai payload terstruktur yang sedang diperiksa. - Interpolasi — compiler mengevaluasi seluruh teks Aggregate sebagai template, sebelum membacanya sebagai YAML, dan mengganti setiap referensi
{{ .parameters.<slot> }}dengan nilai yang telah di-resolve; setiap{{lain dalam teks juga dibaca sebagai sintaks template, sehingga nilai yang membawa kurung kurawal gandanya sendiri menuliskan setiap{{sebagai{{"{{"}}(lihat Teks yang membawa kurung kurawal gandanya sendiri). Interpolasi adalah jalur substitusi untuk permukaan value-template — setelah tahap ini, konteks value-template tidak lagi membawa.parameters; permukaan tersebut menggunakan nilai yang telah di-resolve dan dituliskan ke dalam stringvalues:di sekitarnya. Map gabungan tetap dapat dibaca setelah interpolasi, sepanjang seluruh proses rendering, khusus untuk mendukung evaluasi path-template. Masa keterbacaannya dibatasi oleh masa build: compiler menyerahkan tampilan yang telah di-resolve kepada kompilasi yang menggunakannya alih-alih mengembalikannya kepada pemanggil, sehingga tidak ada apa pun di luar build tersebut yang dapat menjangkau map itu. Permukaan path-template (Releasedirectory:/subDirectory:) membaca.parameters.<slot>selama rendering terhadap allowlist tertutup yang didokumentasikan dipath-template-variables.md.
Template di dalam string YAML Aggregate (values: component, values: feature, ekspresi pass-through parameters: sub-aggregate) membaca map .parameters melalui sintaks template Go standar selama tahap interpolasi. Template di dalam file Recipe dan FeatureRecipe TIDAK menerima .parameters dalam konteks templatnya (lihat “Batas dengan konteks template downstream” di bawah untuk kontrak per permukaan).
Teks yang membawa kurung kurawal gandanya sendiri
Karena seluruh teks adalah templat, kurung kurawal ganda yang merupakan bagian dari sebuah nilai, bukan bagian dari templat, juga dibaca sebagai aksi templat. Definisi platform alur yang dibawa dalam values: sebuah komponen adalah kasus yang umum: n8n membungkus setiap ekspresi dalam parameter sebuah node dengan kurung kurawal ganda, seperti dalam ={{ $json.body.message }}, sebuah prompt Flowise menamai variabel sebagai {{question}} dan sebuah chatflow Flowise menulis {{chatOpenAI_0.data.instance}} untuk setiap koneksi antara dua node, dan sebuah ekspor Langflow membawa kode sumber komponen-komponennya, tempat kurung kurawal tersebut juga dapat muncul. Jika ditulis ke dalam sebuah Aggregate apa adanya, kurung kurawal tersebut menghentikan build pada Aggregate tersebut dengan E0158, yang dijelaskan di bawah “A {{ .parameters.* }} reference cannot be interpolated (Referensi tidak dapat diinterpolasi)” pada Fatal halts; alasannya menyebutkan baris dan token pertama yang tidak dapat dibaca oleh mesin templat — undefined variable "$json" untuk ekspresi n8n. Komentar YAML juga merupakan teks templat, sehingga {{ yang ditulis dalam komentar menghentikan build dengan cara yang sama.
Tulis setiap {{ dalam nilai seperti itu sebagai {{"{{"}}. Itu adalah aksi templat yang hasilnya adalah string {{, sehingga interpolasi mengembalikan kedua kurung kurawal tersebut. Penutup }} tidak memerlukan apa pun, karena di luar sebuah aksi ia adalah teks biasa. Interpolasi dijalankan satu kali, atas teks Aggregate, dan templat Recipe menuliskan apa yang dibacanya dari .values sebagai data, sehingga kurung kurawal yang dikembalikan mencapai keluaran yang dirender sebagaimana diekspor.
# Aggregate fragment — an n8n workflow definition carried as exportedspec: components: automation: type: core/ai-agent/n8n values: workflow_id: support-reply flow_definition: | { "name": "Support reply", "nodes": [ { "name": "Set reply", "type": "n8n-nodes-base.set", "parameters": { "value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}" } } ], "connections": {} }Platform menerima "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".
Simpan definisi seperti itu dalam block scalar (|), seperti di atas, tempat tanda kutip dari escape tersebut merupakan karakter biasa. Teks Aggregate juga dibaca sebagai YAML sebelum diinterpolasi, dan di dalam string YAML berkutip ganda, " dari escape tersebut menutup string, sehingga file tidak lagi dapat di-parse dan build berhenti dengan galat YAML.
Pola akses .parameters.<slot>
Setiap slot parameter yang dideklarasikan dapat diakses sebagai field pada map .parameters. Akses yang benar secara tipe sesuai dengan type yang dideklarasikan:
# Aggregate fragment — parameter declarationsspec: parameters: region: { type: string, enum: [us-east-1, us-west-2] } cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 } enable_debug: { type: boolean, default: false }
components: web: type: core/web-server:1.0.0 values: region: "{{ .parameters.region }}" # string cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer debug: {{ .parameters.enable_debug }} # booleanTahap interpolasi menghasilkan evaluasi template Go terhadap map .parameters; hasilnya menggantikan ekspresi template di tempatnya dalam dokumen. Skema values: Component / Feature kemudian memvalidasi nilai yang dihasilkan pada fase validasi skema pasca-interpolasi dalam proses resolusi.
Pemberian tanda kutip menentukan tipe yang diangkat
Beri tanda kutip pada referensi yang ditujukan ke leaf string; biarkan tanpa tanda kutip untuk setiap tipe terdeklarasi lainnya. Aturan ini milik YAML sendiri, bukan aturan yang ditambahkan Aggrega di atasnya: interpolasi menyubstitusikan nilai yang dipenuhi ke dalam byte dokumen dan tidak melakukan apa pun selain itu, sehingga parsing berikutnya membaca hasilnya persis seperti membaca scalar lainnya. {{ .parameters.cache_ttl_seconds }} tanpa tanda kutip membawa tipe asli dari nilai yang dipenuhi, dan itulah yang memungkinkan parameter integer mencapai leaf integer dan parameter boolean mencapai leaf boolean. "{{ .parameters.cache_ttl_seconds }}" yang diberi tanda kutip membawa string, dan leaf yang dideklarasikan integer atau boolean menolaknya: nilai yang ditulis gagal pada skema values: Component atau Feature-nya karena tipe, dan diagnostiknya menyebut ketidakcocokan tipe, bukan batasan ruang nilai apa pun yang juga tidak akan dipenuhi oleh string tersebut.
Referensi yang berbagi scalar dengan teks lain adalah string bagaimanapun cara penulisannya, karena dokumen hasil substitusi hanya memiliki satu scalar untuk dibaca — image: app:{{ .parameters.tag }} menghasilkan app:1.4.0. Itulah bentuk yang digunakan ketika parameter non-string harus ditempatkan di leaf string.
Akses slot bertipe objek dan bertipe array
Slot parameter bertipe objek mengekspos properti yang dideklarasikannya sebagai field bertingkat pada map .parameters.<slot>. Slot bertipe array mengekspos semantik slice Go template (range, index, len).
# Aggregate fragment — object-typed parameterspec: parameters: database_config: type: object properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full] }
components: api: type: core/compute/api:1.0.0 values: db_host: "{{ .parameters.database_config.host }}" db_port: {{ .parameters.database_config.port }} db_ssl: "{{ .parameters.database_config.ssl_mode }}"Slot parameter bertipe array mendukung iterasi melalui range:
# Aggregate fragment — array-typed parameterspec: parameters: allowed_hosts: type: array items: { type: string, format: hostname } min: 1
components: ingress: type: core/ingress:1.0.0 values: # Compose a comma-separated list from the parameter array hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"Setiap elemen yang diberikan Release diperiksa terhadap kontrak items sebelum interpolasi, sehingga nilai yang bukan nama host — misalnya * — menghentikan build dengan menyebutkan parameter, elemen, dan formatnya. Nama-nama yang diterima format, beserta apa yang diperiksa masing-masing, tercantum di vocabulary/compact-form-authoring.md.
Pustaka template Sprig tersedia selama interpolasi, menyediakan helper seperti join untuk konversi ringkas dari array ke string:
hosts: "{{ join `,` .parameters.allowed_hosts }}"Semantik pengisian default
Slot parameter dengan deklarasi default: menerima nilai default-nya ketika Release tidak mencantumkan slot tersebut. Default diterapkan sebelum tahap validasi kontrak berjalan, sehingga validasi melihat nilai yang telah di-resolve (yang diberikan Release atau default):
# Aggregatespec: parameters: timeout_seconds: type: integer min: 1 max: 300 default: 30
components: api: type: core/compute/api:1.0.0 values: timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30# Release supplies timeout_seconds: 60 — interpolation uses 60# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)Slot yang ditandai required: true tanpa default: memicu galat pada waktu build ketika Release tidak mencantumkannya (E0165). Galat tersebut menyebutkan slot dan lokasinya dalam kontrak agar dapat diperbaiki oleh penulisnya. Slot yang tidak memiliki required: true maupun default: bersifat opsional: bila dihilangkan, setiap referensi ke slot itu diinterpolasi sebagai kosong, lalu skema values: milik Component menilai hasilnya.
Parameter objek bersarang
Ketika sebuah parameter mendeklarasikan type: object dengan properties: yang anak-anaknya sendiri membawa nilai default:, tiga kasus penulisan menghasilkan hasil yang berbeda. Memahami perbedaan ini penting ketika deklarasi parameter berupa objek terstruktur — konfigurasi basis data, kumpulan feature flag, kebijakan timeout dan retry — alih-alih satu nilai skalar.
Kasus 1 — Release tidak mencantumkan slot induk. Default anak-anak dari kontrak diisikan. Penulis Aggregate yang mendeklarasikan default bersarang mendapatkan perilaku yang dimaksudkannya: ketika tim operasional tidak menyediakan slot, konfigurasi menggunakan default yang terdokumentasi.
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432Kasus 2 — Release menulis induk sebagai map kosong eksplisit. Nilai kosong eksplisit dihormati sebagai opt-out yang disengaja. Default anak-anak TIDAK diisikan; slot tetap kosong. Gunakan bentuk ini ketika tim operasional ingin menekan default bersarang dari kontrak tanpa menyediakan penimpaan — misalnya, ketika konsumen hilir mengharapkan slot ada tetapi kosong.
# Release (parent explicit empty)spec: parameters: database: {}
# Resolved at template-interpolation timeparameters: database: {}Perbedaan dari Kasus 1 ini disengaja: tim operasional dapat menyatakan “gunakan default” (dengan tidak mencantumkan slot) maupun “tekan default” (dengan menulis slot sebagai {}). Hal ini mencerminkan cara Aggrega memperlakukan null eksplisit pada anotasi — anotasi yang ditulis sebagai aggrega.ai/<key>: null merupakan opt-out yang disengaja, berbeda dari tidak mencantumkan anotasi sama sekali.
Kasus 3 — Release menulis induk secara parsial. Anak-anak yang diberikan Release mengambil nilai yang ditulis; anak-anak yang tidak diberikan Release diisi dari default.
# Release (partial)spec: parameters: database: host: "db.prod.example.com"
# Resolved at template-interpolation timeparameters: database: host: "db.prod.example.com" # Release-supplied port: 5432 # filled from defaultIni adalah kasus umum bagi penulis Release yang ingin menimpa field tertentu sambil membiarkan sisanya pada default kontrak.
Kapan menggunakan setiap bentuk
- Hilangkan slot ketika Anda ingin default kontrak diterapkan.
- Tulis
{}ketika Anda dengan sengaja ingin slot ada tetapi kosong — ketika default kontrak tidak sesuai untuk lingkungan Anda dan Anda tidak memiliki penimpaan. - Tulis secara parsial ketika Anda menginginkan sebagian penimpaan dan ingin sisanya menggunakan default kontrak.
Penulis Release yang mengetik database: {} dengan harapan “berikan saya default” akan terkejut — nilai yang di-resolve kosong, bukan default yang terisi. Untuk mendapatkan default, hilangkan slot sepenuhnya.
Pemilahan tiga kasus ini berlaku per saudara di setiap kedalaman sarang. Induk yang ditulis sebagai { connection: {}, other_field: "x" } menghasilkan pohon ter-resolve dengan connection kosong (Kasus 2 pada kedalaman 1) dan other_field berisi nilai yang diberikan Release (Kasus 3 pada kedalaman 0) — kasus-kasus tersebut dipilah secara independen untuk setiap saudara, bukan sebagai satu keputusan untuk seluruh subpohon.
Batas dengan konteks templat hilir
Pemberian akses yang asimetris — templat path membaca .parameters secara langsung; templat nilai tidak — adalah pembeda utama pada batas ini. Semantik batas per permukaan:
- Templat component-
values:pada Aggregate yang menulis{{ .parameters.X }}di-resolve dengan benar saat interpolasi. Literal hasil resolusi ditulis langsung ke dalam string YAML di tempatnya. - Templat
valuesMapping:pada Recipe yang menulis{{ .parameters.X }}adalah permukaan templat nilai; konteks templat tidak membawa.parameters. Penulis yang memerlukan variasi per lingkungan dalamvaluesMapping:mengungkapkannya melalui jalur konsumsi.values.<key>yang telah di-resolve — Aggregate mengekspos sebuah parameter, mereferensikannya darivalues:milik sebuah Component, Release memenuhinya, dan nilai pasca-interpolasi mengalir hingga ke Recipe. - Templat
injectMapping:,provides:, ataupipeline.with:pada FeatureRecipe adalah permukaan templat nilai; sama sepertivaluesMapping:pada Recipe..parameterstidak ada dalam konteks templat. - Templat isi Workload (konten
workload:di dalam sebuah Recipe) adalah permukaan templat nilai; sama. - Templat path (batas Release
directory:/subDirectory:) adalah pengecualiannya. Konteks templat path menyertakan.parameters.<slot>terhadap allowlist yang tertutup; referensi di-resolve saat rendering menempatkan output setiap batas. Lihatpath-template-variables.mduntuk matriks lengkap variabel templat path.
Batas kepemilikan empat domain dipertahankan oleh permukaan mana yang menerima parameter, bukan oleh ada atau tidaknya peta parameter di memori pada tahap pipeline tertentu. Templat path ditulis dan dimiliki oleh operator; memberinya akses parameter langsung menjaga urusan operator (tata letak artefak per lingkungan) tetap di dalam permukaan operator. Templat nilai ditulis oleh katalog; menolak akses parameter langsung baginya menjaga penulisan di sisi katalog tetap terkopel longgar dengan kontrak Aggregate-sebagai-Sumber-Kebenaran-Tunggal.
Peta parameter hasil penggabungan tetap dapat dibaca hingga setiap fase render selesai, dan tidak lebih lama dari itu: peta tersebut hanya dapat dijangkau dari kompilasi tempat ia di-resolve, sehingga masa hidupnya dibatasi oleh masa hidup build.
Penjembatanan lintas pilar
Parameter diinterpolasi ke dalam string values di sekitarnya selama resolusi. Nilai hasil interpolasi dapat masuk ke pilar mana pun yang ditulis oleh Aggregate pada cakupannya: string values: komponen, string values: fitur, deklarasi penerusan parameters: sub-aggregate (di mana nilai parameter Aggregate induk diresolusi lalu diteruskan ke slot parameter Aggregate anak), serta string metadata name: / labels:.
Penjembatanan ini bersifat satu arah: nilai parameter mengalir dari .parameters.<slot> yang disediakan oleh Release (atau yang diisi dengan nilai bawaan) ke dalam string YAML di lokasi rujukan. Parameter tidak mengalir ke arah sebaliknya — parameter tidak dapat membaca field values:, field provides:, atau konten pilar lainnya. Sifat satu arah ini merupakan bagian dari jaminan kontrak parameter yang hanya berlaku pada waktu kompilasi.
Rujukan silang
- Untuk bentuk deklarasi kontrak parameter bertipe pada Aggregate:
entities/aggregate.md§“Kontrak parameter bertipe”. - Untuk konteks templat yang lebih luas yang dikonsumsi oleh Recipes pada perenderan dasar (
.values,.infra,.uses,.context.*, dll.): template-context-contract.md. - Untuk ketersediaan per situs templat di sepanjang pipeline kompilasi (bidang mana yang tersedia di situs evaluasi mana): expansion-matrix.md.
- Untuk daftar periksa pengangkatan parameter (empat titik sentuh penulisan yang berurutan — deklarasi Aggregate, referensi values, pemenuhan Release, konsumsi Recipe):
vocabulary/data-pillars.md§“Daftar periksa pengangkatan parameter”. - Untuk kumpulan pilar data yang lebih luas (
values:,infra:,provides:,uses:,features:,locals:,parameters:):vocabulary/data-pillars.md.