Permukaan validasi
Aggrega memvalidasi konten yang ditulis melalui empat lapisan skema yang berbeda. Setiap lapisan mencakup cakupan yang berbeda, berjalan pada titik yang berbeda dalam pipeline kompilasi, dan menghasilkan error dengan bentuk yang berbeda. Penulis yang menemui error validasi akan terbantu dengan mengetahui lapisan mana yang menolak input — field yang sama dapat diatur oleh lebih dari satu lapisan, dan lapisan yang terpicu menentukan apa yang harus diperbaiki dan di mana.
Halaman ini mendokumentasikan keempat lapisan, penempatannya dalam pipeline, konvensi bentuk error yang diikuti setiap lapisan, dan cara lapisan-lapisan berinteraksi ketika lebih dari satu lapisan berlaku pada field yang sama.
Keempat lapisan
Lapisan 1 — Amplop JSON Schema
Cakupan. Bentuk struktural setiap YAML katalog: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, blok spec: tingkat atas, dan field wajib per entitas yang dideklarasikan skema. Setiap jenis entitas (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) memiliki JSON Schema sendiri, yang didokumentasikan dalam referensi skema. Workload juga memilikinya di sana, dan Workload adalah satu-satunya jenis dalam himpunan itu yang ditulis penulis di dalam entitas lain — blok workload: milik Recipe atau FeatureRecipe, atau entri WorkloadLibrary — alih-alih sebagai file katalog tersendiri; pemeriksaan amplop yang sama berlaku padanya di mana pun ia ditulis, dan aggrega validate menerima file Workload secara langsung sebagai target entitas tunggal.
Validasi dijalankan. Saat resolusi (resolver / load), per file. Setiap dokumen diperiksa terhadap JSON Schema jenisnya saat dimuat; key di luar field yang dideklarasikan skema ditolak di sana, sebelum validasi lebih lanjut dijalankan.
Bentuk galat. Ketidakcocokan skema dilaporkan sebagai kegagalan amplop dokumen. Kepalanya memuat kategori dokumen yang bermasalah — [CATALOG_ERROR E0215] untuk entitas katalog, [DEVELOPER_ERROR E0215] untuk Aggregate, [OPS_ERROR E0215] untuk Release — dan pesannya menyebutkan jenis, file, baris dan kolom, path field, serta batasan yang dilanggar:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schemaField wajib yang tidak diisi dan ketidakcocokan tipe muncul dalam bentuk yang sama — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Lapisan 2 — Skema pilar (schema: / featuresSchema / usesSchema)
Cakupan. Pilar data yang dibawa sebuah entitas — values, infra, parameters, ditambah blok lampiran features: yang slotnya dideklarasikan oleh featuresSchema dan blok uses: yang diatur oleh usesSchema. Entitas Domain 2 (Component, Feature) menyematkan deklarasi JSON Schema 2020-12 dalam amplop YAML-nya (spec.schema inline — bentuk ringkas atau lengkap — atau $ref: ke entri SchemaLibrary bersama); entitas Domain 3 (Recipe, FeatureRecipe) menggunakan skema yang telah di-resolve selama tahap validasinya sendiri.
Validasi dijalankan. Saat resolusi, setelah amplop JSON Schema lolos. Kompiler menyusun schema: yang ditulis pada entitas dengan basis yang dibuat otomatis dari deklarasi usesSchema dan featuresSchema; skema hasil susunan memvalidasi blok values: / infra: / features: / uses: yang diberikan pengembang pada setiap instans komponen dalam Aggregate.
Bentuk galat. Pelanggaran batasan muncul sebagai pesan yang menyebutkan entitas, path di dalam pilar, dan aturan yang menolak nilai — misalnya pengembang menetapkan port ke 80 terhadap aturan skema yang mensyaratkan >=1024.
Entri usesSchema atau featuresSchema yang dideklarasikan ulang tidak menghasilkan kegagalan penyusunan. Kedua permukaan itu saling menimpa berdasarkan nama: entri turunan menggantikan entri basis sepenuhnya, skema dan selektor sekaligus, sehingga tidak ada konflik antara entri basis dan entri turunan yang perlu dilaporkan.
Lapisan 3 — Kapabilitas mode tersintesis Provider
Cakupan. Diatur oleh gerbang kapabilitas mode tersintesis dari provider yang terikat:
- Dukungan mode tersintesis (
workload:) bergantung pada kapabilitas provider yang terikat, bukan pada keberadaanworkloadSchema: Recipeworkload:yang terikat pada provider yang tidak dapat melakukan sintesis ditolak di sini. Katalog pustaka standar mendeklarasikanworkloadSchemapada provider yang mampu melakukan sintesis sesuai konvensi — padaspec.provider.workloadSchemamilik Plugin perender provider — sebagai kontrak terjemahan yang terdokumentasi. IsiworkloadSchemaitu sendiri dikompilasi menjadi JSON Schema 2020-12 saat Plugin dimuat, sebuah gerbang penerimaan struktural yang menolak skema yang cacat saat pemuatan, bukan saat perenderan.
Validasi dijalankan. Saat perenderan basis, setelah valuesMapping milik Recipe itu sendiri di-resolve. Lapisan 3 menggerbangi dispatch mode tersintesis berdasarkan kapabilitas provider.
Bentuk galat. Penolakan kapabilitas diatribusikan ke domain penulisan katalog, sehingga laporannya dibuka dengan kepala dalam kurung siku yang membawa kategori tersebut dan instans yang bermasalah. Pesan dibuka dengan kalimat tetap yang menyatakan kondisinya, lalu menyebutkan node, provider, dan jenis yang didukung provider tersebut:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesizedKepala [CATALOG_ERROR] menandakan bahwa entitas katalog yang bermasalah, bukan Aggregate milik pengembang. Di terminal, kepala tersebut juga membawa kode singkat kondisi — E0265 untuk kondisi ini, yang di-resolve oleh tabel setiap kondisi — dan pesannya berpindah ke barisnya sendiri yang menjorok; bentuk satu baris di atas adalah yang sampai ke log. Kalimat pembuka bersifat tetap untuk setiap kondisi, sehingga bagian itulah yang dicocokkan saat Anda bekerja dari teks; segala sesuatu setelahnya bervariasi sesuai node yang bermasalah.
Pengaman terkait melindungi dispatch provider itu sendiri: ketika lebih dari satu Plugin perender provider melayani target yang sama, workspace menyelesaikan ambiguitas tersebut melalui binding provider di .aggrega-config.yaml, yang dipilih saat aggrega pull dan dicatat dalam lockfile. Tanpa binding dan dengan tepat satu Plugin kandidat, kandidat itu digunakan; tanpa binding dan dengan lebih dari satu kandidat, build berhenti secara eksplisit sambil menyebutkan plugin kandidat. Ambiguitas diselesaikan per workspace di titik penggunaan, bukan oleh aturan keunikan di seluruh katalog.
Validasi konten Workload per provider.
spec.provider.workloadSchemamilik Plugin yang me-render provider mendokumentasikan cara provider menerjemahkan sebuah Workload dan menandai provider tersebut mampu menyintesisnya; ia tidak memvalidasi apa pun. Setiap badan Workload divalidasi terhadap skema Workload platform, apa pun provider-nya.
Lapisan 4 — Validasi nilai binding anotasi
Cakupan. Nilai anotasi yang ditulis pada batas Release / komponen batas atau subsistem Aggregate / instans komponen, ketika binding Manifest di bawah mappings.features.annotations.<key> mendeklarasikan perutean melalui daftar path bertitik maps.infra dan/atau maps.values. Setiap path yang dideklarasikan menelusuri spec.schema.<pillar> milik Feature target hingga ke properti daun; kontribusi nilai anotasi pada daun tersebut divalidasi terhadap tipe yang dideklarasikan skema Feature. Validasi mengalir melalui deklarasi JSON Schema 2020-12 milik Feature itu sendiri — binding hanya mendeklarasikan perutean, bukan fragmen validasi.
Validasi dijalankan. Pada sub-fase ekspansi anotasi dalam resolusi, setelah validasi target binding Manifest (pemeriksaan saat pemuatan katalog yang memastikan setiap path yang dideklarasikan ada dalam skema Feature yang dirujuk) dan bersamaan dengan validasi skema Lapisan 2 pada lampiran eksplisit. Untuk setiap anotasi efektif per komponen: nilai di-parse sebagai skalar, map terstruktur, atau null eksplisit; dirutekan per subkey melalui deklarasi maps binding yang dikelompokkan per pilar dengan penegakan sisi-terhadap-pilar (sisi Aggregate memicu maps.values; sisi Release memicu maps.infra); nilai runtime per daun divalidasi terhadap tipe yang dideklarasikan skema Feature pada pilar yang dirutekan. Beberapa galat subkey dikumpulkan dan dikeluarkan semuanya sebelum berhenti.
Bentuk galat. Galat validasi skema pada lapisan ini mengikuti bentuk Lapisan 2 — entitas, path (key anotasi ditambah rute subkey), detail batasan. Pelanggaran partisi sisi-terhadap-pilar dan kegagalan perutean ambigu diatribusikan ke dokumen tempat nilai anotasi ditulis, sehingga kesalahan yang dibawa oleh Aggregate membuka kepala [DEVELOPER_ERROR] dan yang dibawa oleh Release membuka kepala [OPS_ERROR], dan keduanya menyebutkan key anotasi, pilar yang dirutekan, sisi penulisan, dan lokasi sumber.
Satu konvensi pemformatan galat di seluruh lapisan
Keempat lapisan berbagi satu konvensi yang dapat diamati: setiap kegagalan validasi yang dapat diatribusikan ke Aggrega memiliki bentuk jalur-plus-alasan yang menyebutkan field yang bermasalah dan batasan yang menolaknya.
- Galat Lapisan 1 (amplop) dan Lapisan 2 (skema pilar) diawali dengan kepala bertanda kurung siku yang sama — kategori dokumen yang bermasalah dan kode singkat kondisinya, seperti
[CATALOG_ERROR E0215]untuk ketidakcocokan amplop pada entitas katalog dan[DEVELOPER_ERROR E0168]untuk nilai Aggregate yang ditolak skema pilar — diikuti path field dan aturan skema yang dilanggar. - Galat Lapisan 3 (sumber Provider / Workload) menurut definisinya dapat diatribusikan ke entitas katalog — pasangan Recipe + Provider yang menulis skema yang menolak masukan pengembang. Galat ini diatribusikan ke domain penulisan katalog, dan atribusi tersebut sampai kepada Anda melalui kepala diagnostik yang berkurung siku, bukan sebagai kata yang diketik di dalam pesan: laporan yang menghentikan proses diawali dengan
[CATALOG_ERROR E0nnn], dengan kategori menyebutkan domain dan kode pendek menyebutkan kondisinya. Cocokkan berdasarkan kode pendek, yang bersifat tetap setelah diterbitkan. - Galat Lapisan 4 (validasi nilai pengikatan anotasi) mengikuti bentuk Lapisan 2 — skema Feature yang memvalidasi berada di
spec.schemamilik Feature yang dirujuk, dan nilai runtime mengalir melalui peruteanmapspada pengikatan Manifest ke dalam skema tersebut untuk pemeriksaan tipe per daun.
Untuk inventaris lengkap sentinel berprefiks Aggrega dan permukaan yang menghasilkannya, lihat errors/error-translation.md. Untuk katalog per galat (aturan bentuk Recipe [CATALOG_ERROR], kondisi demi kondisi), lihat errors/fatal-halts.md.
Interaksi lapisan ketika bidang tumpang tindih
Field tertulis yang sama dapat diatur oleh lebih dari satu lapisan. containers.<name>.ports.<port> milik Workload diperiksa oleh Lapisan 1 sebagai bagian dari bentuk struktural skema Workload; Lapisan 2 tidak menjangkaunya, karena konten Workload adalah struktur internal Recipe, bukan pilar Component; dan workloadSchema milik provider tidak memeriksa apa pun — sehingga batasan seperti menolak port di bawah 1024 seharusnya ditempatkan di skema Component atau dalam sebuah asersi, tempat lapisan yang terpicu menyebutkannya.
Ringkasan penempatan dalam pipeline
| Lapisan | Cakupan | Dijalankan pada | Prefiks galat |
|---|---|---|---|
| 1 — Amplop JSON Schema | Bentuk struktural (apiVersion, kind, metadata, spec tingkat atas) | Resolusi (pemuatan) | kategori dokumen dengan E0215 — [CATALOG_ERROR E0215] untuk entitas katalog |
2 — Skema pilar (schema: / featuresSchema / usesSchema) | Validasi data per pilar (values, infra, secrets, uses) | Resolusi (setelah envelope) | kategori dokumen penulisnya dengan kode singkat kondisi — [DEVELOPER_ERROR E0168] untuk nilai Aggregate |
| 3 — Gerbang kapabilitas Provider | Dukungan mode tersintesis (kapabilitas provider) | Rendering dasar | [CATALOG_ERROR] |
| 4 — Validasi nilai pengikatan anotasi | Kontribusi nilai anotasi yang dirutekan ke spec.schema milik Feature target melalui jalur maps pada pengikatan Manifest | Subfase ekspansi anotasi dalam resolusi, bersamaan dengan Lapisan 2 | galat validasi skema; permukaan side-vs-pillar / perutean ambigu dibuka dalam domain dokumen penulisnya sendiri — [DEVELOPER_ERROR] dari Aggregate, [OPS_ERROR] dari Release |
Rujukan silang
errors/error-translation.md— inventaris sentinel berprefiks Aggrega dan permukaan yang menghasilkannya.errors/fatal-halts.md— katalog per galat untuk setiap penghentian fatal yang dihasilkan kompiler.vocabulary/data-pillars.md— pilar data (values,infra,parameters,locals,features:,uses:, danprovides) yang divalidasi oleh Layer 2.entities/component.md— permukaan penulisan Component untukschema:/featuresSchema/usesSchema.entities/plugin.md— permukaan penulisan Plugin perender penyedia untukspec.provider.workloadSchema.entities/manifest.md— permukaan pengikatanfeatures.annotationsmilik Manifest (Layer 4).providers/well-known-annotations.md— penguraian nilai anotasi, perutean subkunci nilai terstruktur, opt-out null per subkunci, dan komposisi lintas sisi yang divalidasi oleh Layer 4.