Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

SchemaLibrary

SchemaLibrary adalah entitas katalog yang menyimpan definisi JSON Schema 2020-12 yang dapat digunakan ulang beserta helper berparameter opsional. Components dan Features yang berbagi bentuk skema — URL, durasi, struktur probe umum, batas sumber daya yang berulang — mendeklarasikan bentuk tersebut satu kali dalam sebuah library dan mereferensikannya melalui URI $ref kanonis. Entitas library ini berada di Tier 3: bersifat opt-in untuk katalog yang memerlukan penggunaan ulang skema lintas Component. Katalog tanpa konten skema yang berulang dirilis tanpa SchemaLibrary apa pun.

Peran SchemaLibrary

Arsitek platform menulis SchemaLibraries untuk memusatkan bentuk skema yang berulang di seluruh katalog. Sebuah library bukan blok bangunan yang dapat di-deploy; library adalah namespace definisi. Penulis Component / Feature mereferensikan entri library melalui URI $ref kanoniknya, yang diberi tipe satu kali dan divalidasi di mana pun referensi tersebut di-resolve.

Pemisahan antara “library” dan “konsumen” disengaja. Components mendeklarasikan kontrak yang diisi oleh sebuah instans (values, infra, dan provides-nya, socket-nya, slot kredensialnya). Features menyandikan lampiran perilaku. SchemaLibraries hanya menyandikan konten skema — aturan struktural yang harus dipenuhi oleh sebuah nilai. Dengan menjaga ketiga peran tersebut tetap terpisah, setiap jenis entitas dapat berkembang dengan iramanya sendiri; penulis yang tidak memerlukan definisi skema bersama tidak pernah berurusan dengan entitas library.

Amplop entitas

Entitas SchemaLibrary membawa amplop katalog standar. apiVersion: aggrega.ai/v1beta1 dan kind: SchemaLibrary menandai jenis entitas; metadata.name adalah pengidentifikasi PascalCase; metadata.version mengikuti semantic versioning yang ketat. Konten pustaka berada di bawah spec: spec.schemas wajib ada (pustaka harus mendeklarasikan setidaknya satu entri), dan spec.templates bersifat opsional (hanya ada jika pustaka menggunakan helper berparameter).

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

Menulis entri skema

Entri skema ditulis dalam salah satu dari tiga bentuk. Bentuk ringkas adalah permukaan bawaan untuk bentuk pendek yang umum — type, pattern, enum, min, max, dan batasan satu baris serupa. YAML JSON Schema 2020-12 adalah opsi penulisan yang setara untuk entri yang memerlukan permukaan JSON Schema lengkap (kata kunci komposisi, bentuk kondisional, $defs yang kompleks). Pencampuran keduanya dalam satu entri didukung melalui pengiriman berdasarkan bentuk konten per node pada kompiler bentuk ringkas; jalan keluar $jsonschema: menyematkan konten JSON Schema lengkap pada node mana pun ketika bentuk ringkas tidak dapat mengungkapkan maksudnya.

Sebuah format dalam entri memeriksa hal yang sama seperti di skema mana pun: ia menyebut salah satu dari email, uri, hostname, ipv4, ipv6, uuid, date-time, dan date, dan nilai yang diberikan konsumen untuk field tersebut ditolak kecuali memiliki format itu — lihat vocabulary/compact-form-authoring.md. Entri yang menyebut format lain — termasuk password — ditolak saat pustaka dimuat, sehingga aggrega validate atas seluruh katalog menolaknya terlepas dari apakah sudah ada yang mereferensikannya, dengan menyebut pustaka, entri, dan nama tersebut serta mencantumkan format yang didukung, dan build atau pull yang Release-nya menjangkau pustaka tersebut akan berhenti karenanya. Entri yang mereferensikan pustaka lain dinilai di tempat pilar Component atau Feature mengonsumsinya. Field yang membawa materi rahasia mendeklarasikan sensitive: true alih-alih sebuah format.

Templat dan $instantiate:

Library dengan struktur berulang yang substansial mendeklarasikan helper berparameter di bawah spec.templates. Sebuah templat membawa map $params: (deklarasi parameter bertipe yang diberi nama) ditambah sebuah body (bentuk ringkas atau konten JSON Schema yang mereferensikan parameter sebagai token skalar $<paramName>). Entri skema menginstansiasi templat melalui binding $instantiate: + $args:; mesin substitusi mengganti placeholder parameter dengan nilai skalar literal dan menghasilkan body entri yang telah diresolusi.

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

Substitusi hanya berupa skalar literal. Mesin substitusi tidak menginterpretasikan sintaks templat Go, tidak mengevaluasi kondisional, dan tidak menjalankan perulangan. Penulis yang membutuhkan helper yang lebih ekspresif menyusun Components atau Features yang mengonsumsi entri library dengan variasinya sendiri.

Konvensi penamaan

Nama pustaka, kunci entri skema, dan nama templat mengikuti PascalCase. JSON Schema amplop entitas menegakkan konvensi ini pada tiga posisi melalui batasan pola:

  • metadata.name cocok dengan ^[A-Z][A-Za-z0-9]*$.
  • Kunci map spec.schemas cocok dengan pola yang sama melalui propertyNames.
  • Kunci map spec.templates cocok dengan pola yang sama melalui propertyNames.

SchemaLibrary dengan kunci non-PascalCase di spec.schemas atau spec.templates gagal dalam validasi amplop saat workspace dimuat. Penegakan di tingkat amplop ini penting: kunci entri skema muncul dalam URI $id kanonis (#/schemas/<name>); nama templat merujuk ke URI kanonis pada saat instansiasi. Menangkap kunci non-PascalCase saat pemuatan mencegahnya menyebar ke seluruh ekosistem katalog.

Nama parameter di dalam map $params: sebuah templat bersifat lokal bagi templat tersebut — nama ini tidak muncul dalam URI $id kanonis dan tidak dibatasi pola di tingkat amplop. Penulis mengikuti konvensi penamaan apa pun yang sesuai dengan parameter templat; port, path, intervalSec, dan nama parameter huruf kecil serupa adalah hal yang lazim.

Keseragaman penamaan di tingkat pustaka, skema, dan templat membuat pengidentifikasi referensi mudah dipindai: WebPrimitives#/schemas/URL dapat dipahami sekilas.

Untuk semantik resolusi $ref: lintas dokumen — bagaimana $ref: diselesaikan melintasi batas SchemaLibrary, perbedaan sintaks required: untuk konsumen yang memuat $ref:, ekspansi rantai pustaka-ke-pustaka, dan perilaku konsumen yang mempersempit pustaka — lihat vocabulary/cross-document-ref.md.

Mereferensikan entri pustaka

Penulis Component / Feature mereferensikan entri pustaka berdasarkan identitasnya — bentuk nama polos <Library>#/schemas/<name>:

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

Nama pustaka diresolusi terhadap katalog yang telah diresolusi; fragmen #/schemas/<name> memilih entrinya. Sebuah referensi tidak membawa host registri; penulis dapat menyatakan batas bawah versi minimum opsional sebagai <Library>:<version>#/schemas/<name> (pemisah versinya adalah :, sesuai dengan pemetaan recipe/feature dan pin lockfile), tetapi versi yang diresolusi disediakan oleh lockfile per Release, yang mem-pin setiap pustaka yang digunakan berdasarkan nama + versi + digest konten. Referensi yang membawa host registri — bentuk oci://<host>/… — ditolak saat kompilasi dengan diagnostik yang mengarahkan penulis ke bentuk identitas, sehingga lokasi fisik registri tidak pernah masuk ke sumber yang ditulis. Dari mana byte pustaka disajikan (direktori katalog lokal, cache konten, atau registri jarak jauh) adalah urusan resolver, yang diikat pada saat resolusi; memindahkan registri merupakan perubahan konfigurasi resolver, bukan perubahan sumber.

Kata kunci JSON Schema yang dilarang

Kata kunci JSON Schema 2020-12 $dynamicAnchor dan $dynamicRef dilarang dalam entri SchemaLibrary. Parser SchemaLibrary memindai entri skema maupun badan templat pada saat pemuatan workspace; publishing-linter menerapkan pengaman redundan pada saat publikasi; mesin instansiasi memindai ulang badan yang telah di-resolve setelah substitusi parameter, sehingga templat yang menyelundupkan kata kunci terlarang melalui nilai parameter tetap gagal. Ketiga pemindaian ini bersama-sama menutup jalur pengenalan statis ($dynamicAnchor literal dalam entri skema atau badan templat), jalur pengenalan parametris (nilai $args: yang berisi $dynamicRef), dan jalur pengelakan melalui perkakas di luar jalur (pengaman saat publikasi menangkap apa pun yang melewati parser).

Ketika penolakan terjadi, galat menyebutkan kata kunci yang melanggar dan path berkasnya. Penulis melihat galat tersebut pada saat penulisan, bukan pada instansiasi pertama; badan templat tidak dikecualikan dari pemindaian saat pemuatan.

Semantik referensi dinamis terkait dengan evaluasi runtime dengan cara yang merusak kontrak determinisme waktu kompilasi milik compiler. Penulis yang membutuhkan perilaku referensi dinamis menyusun ulang skema agar menggunakan resolusi $ref statis; pemeriksaan ini tidak dapat dinonaktifkan.

Penempatan tier

SchemaLibrary berada di Tier 3 dalam model dokumentasi tingkatan entitas — bersifat opsional untuk katalog yang memerlukan penggunaan ulang skema lintas Component. Katalog tanpa konten skema yang berulang dirilis tanpa entitas SchemaLibrary apa pun; penandaan tingkatan ini menyatakan “lanjutan; lewati jika tidak diperlukan” untuk navigasi dokumentasi, bukan kapabilitas. Kompiler memperlakukan SchemaLibrary secara seragam dengan jenis entitas katalog lainnya: validasi envelope yang sama saat pemuatan workspace, pipeline JSON Schema 2020-12 yang sama untuk konten per entri, dan pipeline publikasi OCI yang sama saat rilis.

Di dalam Tier 3, mekanisme helper parametrik spec.templates itu sendiri bersifat opsional. Pustaka dengan struktur berulang yang substansial (templat Probe yang diparameterisasi atas port + path; templat CORS yang diparameterisasi atas allowed-origins; templat TLS yang diparameterisasi atas path cert + key) mendapat manfaat dari penggunaan ulang templates; pustaka dengan entri sekali pakai yang beragam melewati blok templat sepenuhnya dan menulis setiap entri secara inline di bawah spec.schemas.