Skema Aggrega Catalog (Feature)
Referensi yang dihasilkan. Jangan diedit secara manual — hasilkan ulang dari JSON Schema yang dipublikasikan.
ID skema: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Fitur operasional modular yang terikat secara dinamis ke komponen.
Lihat referensi penulisan Feature untuk panduan prosa tentang penulisan entitas Feature; 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 “Feature” | ya | Konstanta: "Feature" |
metadata | object | ya | |
spec | object | ya | Kontrak validasi, penargetan, dan interoperabilitas untuk Feature katalog: pilar bentuk bebas (values, infra, provides) yang ditulis melalui skema, pilar bentuk tetap (soket dependensi usesSchema, slot lampiran featuresSchema), penargetan komponen (appliesTo dan appliesToAnyOf), serta kontrol interoperabilitas. |
Properti tambahan tidak diizinkan.
feature.metadata
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | Panjang minimal 1 karakter. |
version | string | ya | Semantic Versioning ketat dari fitur (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 | tidak | Label duck-typing untuk Feature. Label khusus ‘feature.aggrega.ai/kind’ dengan nilai ‘secret’ menandai ini sebagai Feature kredensial bagi penulis dan bagi perkakas yang menampilkannya. Feature kredensial dan Feature biasa dilampirkan dengan cara yang sama, di bawah permukaan lampiran yang sama; apa yang dihasilkan sebuah lampiran ditentukan oleh FeatureRecipe yang dipetakan oleh Manifest untuk jenisnya, bukan oleh label tersebut. |
annotations | map of string | tidak | Karakteristik fitur intrinsik dan tidak dapat diubah yang ditulis oleh Platform Architect di Domain 2. Diturunkan ke bucket .context.annotations.catalog. |
Properti tambahan tidak diizinkan.
feature.metadata.maintainers[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | |
email | string | tidak | |
url | string | tidak |
Properti tambahan tidak diizinkan.
feature.metadata.labels
Label duck-typing untuk Feature. Label khusus ‘feature.aggrega.ai/kind’ dengan nilai ‘secret’ menandai ini sebagai Feature kredensial bagi penulis dan bagi perkakas yang menampilkannya. Feature kredensial dan Feature biasa dilampirkan dengan cara yang sama, di bawah permukaan lampiran yang sama; apa yang dihasilkan sebuah lampiran ditentukan oleh FeatureRecipe yang dipetakan oleh Manifest untuk jenisnya, bukan oleh label tersebut.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | tidak | Label jenis Feature. Nilai ‘secret’ menandai ini sebagai Feature kredensial. Nilai yang diizinkan: "secret" |
feature.spec
Kontrak validasi, penargetan, dan interoperabilitas untuk Feature katalog: pilar bentuk bebas (values, infra, provides) yang ditulis melalui skema, pilar bentuk tetap (soket dependensi usesSchema, slot lampiran featuresSchema), penargetan komponen (appliesTo dan appliesToAnyOf), serta kontrol interoperabilitas.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
extends | string | tidak | Referensi ke Feature dasar yang diwarisi oleh Feature ini. Referensi ini menyebut Feature dasar melalui metadata.name-nya, bukan melalui koordinat registri tempat Feature tersebut dipublikasikan, dan menerima tiga bentuk versi yang sama dengan setiap referensi katalog: polos (core/queue) untuk rilis tertinggi yang tersedia, tepat (core/queue:1.0.0), atau rentang caret (core/queue:^1.0.0). Yang diwarisi lebih dari sekadar metadata: metadata.labels dan metadata.annotations milik Feature dasar, selektor appliesTo dan appliesToAnyOf-nya, blok interoperability-nya, usesSchema dan featuresSchema-nya semuanya digabungkan ke bawah, dan deklarasi JSON Schema 2020-12-nya pada schema digabungkan secara otomatis. Nilai milik turunan sendiri yang berlaku pada kunci yang sama, dan bidang identitas tidak pernah diwarisi. |
featuresSchema | map of object | tidak | Definisi slot lampiran deklaratif: titik pengikatan bernama tempat Feature ini mengharapkan Feature lain dilampirkan. Sebuah slot membatasi pengisi mana yang dapat mengikatnya (selector) dan bagaimana materi pengisi dapat dikirimkan (inject); Feature milik pengisi itu sendiri yang memiliki kontrak values dan infra-nya. Mendeklarasikan slot tidak pernah menutup blok lampiran — seorang penulis dapat melampirkan Feature dengan nama yang tidak dideklarasikan oleh slot mana pun. Slot adalah titik pengikatan, bukan soket dependensi: usesSchema mendeklarasikan permukaan topologi yang terpisah. |
appliesTo | string | tidak | String label-selector bergaya Kubernetes yang mencocokkan Components. Persyaratan yang dipisahkan koma harus terpenuhi semuanya (AND). Bentuk yang didukung: key=value, key!=value, key in (v1, v2), key notin (v1, v2), key polos (label ada), !key (label tidak ada). Contoh: “tier in (critical, production), !legacy”. Selektor yang kosong atau tidak ada tidak mendeklarasikan batasan apa pun. Selektor dibaca berdasarkan bentuk-bentuk ini setiap kali lampiran Feature ini dievaluasi, dan persyaratan di luar bentuk tersebut menghentikan build dengan menyebutkannya: persyaratan kosong (koma di awal, di akhir, atau ganda), atau kunci yang mengandung spasi atau salah satu dari = ! ( ) dan koma — sehingga “!tier=frontend” ditolak, dan tier!=frontend adalah cara mengecualikan suatu nilai. Nilai adalah teks setelah operatornya, apa pun karakter yang dikandungnya. Pola pada bidang ini hanya menolak beberapa bentuk yang salah format, sebelum lampiran apa pun dievaluasi. Pola: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string atau map dari string[] | tidak | Daftar selektor; Feature berlaku jika SALAH SATU item cocok (logika OR). Setiap item berupa string label-selector (tata bahasa yang sama dengan appliesTo; persyaratan di dalam string digabungkan dengan AND) atau map key-value datar yang setiap pasangannya harus cocok (hanya kesamaan). |
interoperability | object | tidak | Kontrol keamanan operasional dan interoperabilitas lanjutan. |
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 dan mekanisme inject yang diizinkannya. Kunci: satu atau lebih huruf, angka, garis bawah, atau tanda hubung. Titik tidak diizinkan. Pola: ^[a-zA-Z0-9_-]+$. |
schema | object | tidak | Konten JSON Schema 2020-12 yang mencakup pilar bentuk bebas: values (domain Developer — parameter bentuk aplikasi yang dikonfigurasi Developer per lampiran Feature di Aggregate); infra (domain Operator — kenop ukuran fisik yang disediakan oleh Release); dan provides (kunci konteks hilir yang diekspos Feature ini kepada konsumen melalui pipa topologi). Menerima tiga mode penulisan melalui dispatch 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 bidang saat build. Setiap entri adalah asersi bernama: kuncinya adalah pengenal aturan yang stabil yang ditampilkan dalam pesan kesalahan; nilainya adalah string template Go dengan semantik penghentian {{ fail "message" }}. Beberapa asersi bernama per entitas dievaluasi per instans dalam urutan yang dideklarasikan penulis; asersi pertama yang gagal menghentikan build. Asersi Feature dievaluasi setelah resolusi dan analisis statis, sebelum render, serta menyatakan invarian arsitektural dari kontrak. 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 dijalankan, default biasa tidak menyediakan fallback bidang opsional pada permukaan ini — lindungi 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. |
Properti tambahan tidak diizinkan.
feature.spec.interoperability
Kontrol keamanan operasional dan interoperabilitas lanjutan.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
conflictsWith | string[] | tidak | Nama-nama Features yang tidak dapat mencapai satu komponen bersama Feature ini, masing-masing ditulis seperti cara type sebuah lampiran menyebut Feature. Build berhenti sebelum rendering ketika satu komponen akhirnya memuat Feature ini dan Feature yang disebut di sini — baik masing-masing dilampirkan pada komponen, pada subsistem atau boundary yang memuatnya, pada entri komponen Release, maupun melalui ekspansi berbasis anotasi. Satu deklarasi sudah cukup: penghentian tidak memerlukan Feature lain untuk mencantumkan Feature ini. Nama dibandingkan dengan versi apa pun dihapus, sehingga sebuah entri cocok dengan setiap versi Feature yang disebutnya. Dua Features yang dilampirkan pada boundary bersaudara yang tidak berbagi komponen tidak pernah bertemu dan tidak menghentikan build. |
Properti tambahan tidak diizinkan.