Skema Aggrega Catalog (Component)
Referensi yang dihasilkan. Jangan diedit secara manual — hasilkan ulang dari JSON Schema yang dipublikasikan.
Id skema: https://aggrega.ai/schemas/component-v1beta1.schema.json
Definisi abstrak dari sebuah blok bangunan atomik.
Lihat referensi penulisan Component untuk panduan prosa tentang penulisan entitas Component; halaman ini mendokumentasikan skema struktural yang dijelaskan oleh referensi tersebut.
Jenis tingkat teratas: object
Properti
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | ya | Konstanta: "aggrega.ai/v1beta1" |
kind | const “Component” | ya | Konstanta: "Component" |
metadata | object | ya | |
spec | object | ya | Definisi validasi dan skema yang mengatur payload values opak milik pengembang. |
Properti tambahan tidak diizinkan.
component.metadata
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | Panjang minimal 1 karakter. |
version | string | ya | Semantic Versioning ketat dari antarmuka (misalnya, 1.0.0). Pola: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | tidak | Apa entitas ini dan untuk apa, ditulis bagi orang yang sedang memutuskan apakah akan menggunakannya. Awali dengan kalimat yang menyebut hal tersebut, lalu tambahkan apa yang dibutuhkan pembaca untuk memilihnya dan menggunakannya dengan benar — apa yang diharapkannya dari Release yang men-deploy-nya, dan apa pun yang mengejutkan tentang perilakunya. Panjang yang lazim adalah satu paragraf pendek. |
maintainers | object[] | tidak | Daftar pemelihara yang memiliki entitas ini. |
license | string | tidak | Pengidentifikasi SPDX untuk lisensi perangkat lunak yang dideskripsikan entitas ini, seperti MIT atau AGPL-3.0. Pengidentifikasi ini mencatat ketentuan perangkat lunak tersebut, bukan ketentuan berkas ini. |
repository | string | tidak | URL ke repositori Git tempat berkas sumber berada. |
home | string | tidak | URL halaman beranda, wiki, atau dokumentasi entitas ini. |
keywords | string[] | tidak | Daftar kata kunci deskriptif untuk kemudahan penemuan di UI. |
labels | object | ya | Label duck-typing untuk mendeklarasikan karakteristik. Harus menyertakan kunci cadangan ‘component.aggrega.ai/type’. |
annotations | map of string | tidak | Karakteristik komponen yang intrinsik dan tidak dapat diubah, ditulis oleh Platform Architect di Domain 2. Diturunkan ke bucket .context.annotations.catalog. |
Properti tambahan tidak diizinkan.
component.metadata.maintainers[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | |
email | string | tidak | |
url | string | tidak |
Properti tambahan tidak diizinkan.
component.metadata.labels
Label duck-typing untuk mendeklarasikan karakteristik. Harus menyertakan kunci cadangan ‘component.aggrega.ai/type’.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | ya | Sumbu cadangan yang menyatakan jenis komponen ini. Aggrega mendefinisikan kunci ini beserta nilai yang diterimanya, sehingga himpunannya tertutup; untuk mengklasifikasikan komponen pada sumbu Anda sendiri, tambahkan kunci label Anda sendiri di samping kunci ini. Nilai yang diizinkan: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Definisi validasi dan skema yang mengatur payload values opak milik pengembang.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
extends | string | tidak | URI dari Component dasar yang diperluas oleh Component ini. Perluasan menyusun struktur: label dan anotasi metadata milik dasar, slot lampirannya (featuresSchema), allowlist self-inject-nya (inject) dan soket topologinya (usesSchema) diwarisi, dan Component ini dapat menambahkannya atau mengganti entri yang diwarisi kunci demi kunci. Pilar data milik dasar TIDAK disusun — blok schema milik dasar diwarisi persis seperti yang ditulis oleh dasar, sehingga Component yang memperluas menulis schema: inherited dan tidak menulis konten pilar sendiri. |
featuresSchema | map of object | tidak | Definisi slot lampiran deklaratif: titik pengikatan bernama tempat entitas ini mengharapkan sebuah Feature dilampirkan. Slot membatasi isian mana yang dapat mengikatnya (selector) dan bagaimana materi isian dapat dikirimkan (inject); Feature milik isian itu sendiri memiliki values dan kontrak infra-nya. Mendeklarasikan slot tidak pernah menutup blok lampiran — penulis dapat melampirkan Feature dengan nama yang tidak dideklarasikan oleh slot mana pun, sehingga satu entitas melayani baik lampiran yang mengisi slot maupun kredensial yang dibagikan pada cakupan yang lebih luas. Slot adalah titik pengikatan, bukan soket dependensi: usesSchema mendeklarasikan permukaan topologi yang terpisah. |
inject | string[] | tidak | Mekanisme pengiriman self-inject yang diizinkan (misalnya, [‘env’, ‘file’, ‘arg’]). Jika ada, pengembang dapat menggunakan blok inject: pada tingkat komponen di Aggregate untuk menyuntikkan values atau kunci provides mereka sendiri langsung ke dalam pipa pengiriman. Jika dihilangkan, self-inject tingkat komponen dilarang (pola Black-Box — Recipe menangani semua pengkabelan internal). Semantiknya sama dengan usesSchema[].inject tetapi mengatur values milik komponen itu sendiri, bukan topologi lintas komponen. Nama mekanisme apa pun boleh dicantumkan kecuali all, yang tidak dapat disebut oleh blok inject mana pun. |
usesSchema | map of object | tidak | Soket dependensi yang dideklarasikan entitas ini, dengan kunci berupa nama soket; setiap koneksi yang ditarik melalui soket diperiksa terhadap deklarasi soket tersebut — selektornya, mekanisme inject yang diizinkannya, dan kontrak per koneksinya. Kunci: satu atau lebih huruf, angka, garis bawah, atau tanda hubung. Titik tidak diizinkan. Pola: ^[a-zA-Z0-9_-]+$. |
schema | any | tidak | Konten JSON Schema 2020-12 yang mencakup pilar bentuk bebas: values (domain Developer — parameter bentuk aplikasi yang dikonfigurasi Developer per instans Component dalam Aggregate); infra (domain Operator — pengaturan ukuran fisik yang disediakan oleh Release); dan provides (kunci konteks hilir yang diekspos Component ini kepada konsumen melalui pipa topologi). Menerima empat mode penulisan melalui dispatch berdasarkan bentuk konten: (1) konten inline (peta YAML yang memuat bentuk ringkas, JSON Schema YAML, atau campuran); (2) penggantian file melalui {$import: |
assertions | map of string | tidak | Validasi lintas field pada waktu build. Setiap entri adalah asersi bernama: kuncinya adalah pengidentifikasi aturan yang stabil yang ditampilkan dalam pesan error; nilainya adalah string template Go dengan semantik penghentian {{ fail "message" }}. Beberapa asersi bernama per entitas dievaluasi per instans sesuai urutan yang dideklarasikan penulis; asersi pertama yang gagal menghentikan build. Asersi Component dievaluasi setelah resolusi dan analisis statis, sebelum render, serta menyatakan invarian arsitektural dari kontrak yang berlaku terlepas dari Recipe mana yang mengikat. Konteks template: .values / .infra / .uses / .features / .metadata. Evaluator menggunakan missingkey=error: referensi ke kunci yang tidak terdefinisi berhenti dengan diagnostik no-such-key. Karena referensi polos berhenti sebelum fallback apa pun dapat berjalan, default biasa tidak menyediakan fallback field opsional pada permukaan ini — batasi referensi dengan hasKey, atau gunakan helper optional, yang melakukan pemeriksaan keberadaan secara langsung. Membaca kunci melalui index juga tidak menyediakannya: index berhenti pada kunci map yang tidak dimiliki map tersebut, dengan menyebutkan kuncinya. Pewarisan bersifat aditif: Component yang mendeklarasikan extends dievaluasi terhadap asersi yang diwarisinya maupun asersinya sendiri, dengan aturan warisan terlebih dahulu, dan rantai dengan kedalaman berapa pun terakumulasi dari akar rantai ke bawah — sehingga ketika lebih dari satu aturan akan gagal, aturan yang dideklarasikan paling atas dalam rantailah yang dilaporkan. Menggunakan kembali nama warisan untuk mendeklarasikan aturan yang berbeda ditolak ketika rantai extends diresolusi terhadap katalog, dengan menyebutkan kedua Components dan nama yang sama itu — sehingga hal ini muncul setelah Component dasar tersedia, bukan dari dokumen yang memperluas saja; Component yang memperluas menambahkan aturan dan tidak pernah mengganti aturan. Menyatakan ulang aturan warisan secara byte demi byte dengan namanya sendiri diterima sebagai no-op. Tidak ada yang memeriksa apakah dua aturan dapat sama-sama terpenuhi: pasangan yang saling tidak dapat dipenuhi adalah kesalahan penulisan yang muncul sebagai kegagalan asersi biasa ketika sebuah instans memicu yang mana pun yang terpicu lebih dahulu, tidak pernah sebagai peringatan di awal. |
Properti tambahan tidak diizinkan.
Definisi
extending-component-must-declare-schema-inherited
Berlaku jika spec.extends ada. Component yang memperluas menerima values / infra / provides dari basisnya persis seperti yang ditulis oleh basis tersebut, sehingga Component itu mendeklarasikan spec.schema: inherited dan tidak menulis konten pilar. Kedua hasil lainnya adalah galat, dan keduanya merupakan kesalahan yang berbeda: menghilangkan spec.schema sepenuhnya, yang akan membuat pembaca tidak dapat membedakan blok pilar yang diwarisi dari blok yang terlupakan; dan menulis konten pilar di bawah spec.schema, yang akan meminta kontrak kedua yang menyimpang pada Component yang kontraknya adalah kontrak basisnya.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
schema | const “inherited” | ya | Penanda pewarisan, dan satu-satunya nilai yang diambil spec.schema pada Component yang mendeklarasikan extends. Penanda ini menyebutkan asal pilar; konten pilar itu sendiri adalah milik Component basis. Konstanta: "inherited" |
non-extending-component-authors-its-own-schema
Berlaku jika spec.extends tidak ada. Component yang tidak memperluas basis apa pun menulis konten values / infra / provides-nya sendiri di bawah spec.schema, sehingga bidang tersebut memuat konten yang ditulis, bukan penanda inherited: penanda itu menyatakan bahwa pilar berasal dari basis, sedangkan Component ini tidak memilikinya.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
schema | object | tidak | Konten pilar yang ditulis — sebuah map, dalam salah satu dari tiga mode penulisan konten yang didokumentasikan spec.schema. |