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

Penulisan bentuk ringkas

Bentuk ringkas adalah singkatan deklaratif berbentuk YAML untuk JSON Schema 2020-12. Penulis menuliskan batasan per bidang sebagai peta YAML inline-flow (port: { type: integer, min: 1, max: 65535, default: 8080 }); simpul objek perantara berupa penyarangan YAML biasa; referensi menggunakan $ref: standar JSON Schema. Kompiler mengubah bentuk ringkas menjadi JSON Schema 2020-12 sebelum validasi apa pun dijalankan, sehingga validasi, pelaporan galat, dan setiap alat yang membaca skema bekerja pada JSON Schema yang telah di-resolve, dalam bentuk apa pun skema itu ditulis.

Halaman ini mendokumentasikan kosakata bentuk ringkas, konvensi struktural, pemilihan objek tersirat-vs-eksplisit, semantik penutupan, heterogenitas type: yang memungkinkan larik tipe yang diizinkan, kata kunci yang dicadangkan di setiap cakupan bentuk tersirat, dan namespace ekstensi x-aggrega-*. Untuk semantik resolusi $ref: lintas dokumen, lihat cross-document-ref.md. Untuk tata bahasa penulisan blok assertions, lihat templates/assertions-block.md. Untuk himpunan pilar data (values:, infra:, provides:, uses:, features:, locals:, parameters:), lihat data-pillars.md.

Bentuk ringkas adalah permukaan penulisan bawaan untuk schema:, parameters:, dan entri SchemaLibrary. JSON Schema YAML adalah opsi penulisan yang setara; kedua bentuk sama-sama kelas utama dan dapat dicampur dalam satu skema. Kedua bentuk dikompilasi menjadi dokumen JSON Schema hasil resolusi yang sama; perkakas hilir dan validasi tidak mengetahui jalur penulisannya.

Kosakata

Kata kunci bentuk ringkas adalah yang ada di tabel-tabel di bawah. Penulis mempelajarinya sekali dan menerapkannya pada schema:, parameters:, dan entri SchemaLibrary.

Kata kunci tipe dan identitas

Kata kunciArtiDikompilasi menjadi JSON Schema
typeTipe bidang (string, integer, number, boolean, object, array, atau array dari tipe yang diizinkan)type:
descriptionDokumentasi yang dapat dibaca manusiadescription:
defaultNilai default ketika bidang tidak adadefault:
requiredPenanda per daun (required: true) untuk bidang yang harus adaMenambahkan nama bidang ke array required: milik induk

Kata kunci batasan

Kata kunciArtiDikompilasi menjadi JSON Schema
enumNilai yang diizinkan (daftar)enum:
constSatu-satunya nilai yang diizinkan — skalar, pemetaan, atau daftarconst:
minNilai minimum (numerik) atau panjang minimum (string/array)minimum: (numerik); minLength: (string); minItems: (array) — dipilih berdasarkan type:
maxNilai atau panjang maksimum, sejajar dengan minmaximum: / maxLength: / maxItems:
minLength / maxLengthBatasan panjang string eksplisitPemetaan langsung ke minLength: / maxLength: (gunakan ketika min/max akan ambigu)
patternPola regex untuk stringpattern:
formatFormat bernama yang harus dimiliki string — salah satu dari email, uri, hostname, ipv4, ipv6, uuid, date-time, date (lihat Format bernama)format:

Pada blok parameters: sebuah Aggregate, beberapa di antaranya juga diperiksa pada deklarasi itu sendiri, sebelum nilai Release apa pun dibaca. minLength dan maxLength milik parameter itu sendiri bernilai nol atau lebih — nilai negatif ditolak saat Aggregate dimuat — dan setiap pattern, termasuk yang berada di dalam kontrak items, properties atau valuesType bersarang, harus berupa ekspresi reguler yang dapat dikompilasi, karena pola dikompilasi saat kontrak parameter dibaca. Setiap format, pada kedalaman berapa pun, harus salah satu dari format bernama di bawah. min atau max pada parameter bertipe boolean atau object juga ditolak, karena pasangan itu tidak membatasi apa pun pada tipe tersebut. Setiap kesalahan menghentikan build dengan menyebutkan parameternya, baik ada maupun tidak ada Release yang menyediakannya. Batas panjang di dalam kontrak bersarang tidak dikenai batas bawah tersebut; lihat entities/aggregate.md untuk tempat setiap pemeriksaan dijalankan.

Format bernama

format menyebutkan bentuk yang harus dimiliki nilai string. Nama-namanya adalah yang didefinisikan oleh spesifikasi JSON Schema, dieja seperti spesifikasi mengejanya, dan masing-masing memeriksa apa yang didefinisikan spesifikasi sebagai maknanya:

NamaNilai yang sesuai adalahDidefinisikan oleh
emailsebuah mailbox: bagian lokal (atom yang dipisahkan titik, atau string berkutip), @, lalu domain atau literal alamat dalam kurung siku — ops@example.com. Nama tampilan seperti Joe <joe@example.com> bukan mailboxRFC 5321, bagian 4.1.2 (Mailbox)
uriURI absolut: skema, :, lalu sisanya, dengan setiap karakter di luar alfabet URI dienkode persen — https://example.com/a%20b, s3://bucket/key. Referensi relatif seperti /path bukan URI absolutRFC 3986 (URI)
hostnamenama host: label yang dipisahkan titik, terdiri dari huruf, angka, dan tanda hubung, masing-masing 1–63 karakter yang tidak diawali maupun diakhiri tanda hubung, paling banyak 253 karakter secara keseluruhan — db-primary.data.svc.cluster.local. Label Punycode (xn--…) diterima sebagaimana ditulis; wildcard *, garis bawah, atau titik di akhir tidak diterimaRFC 1123, bagian 2.1
ipv4empat bilangan desimal dari 0 hingga 255, dipisahkan titik — 192.0.2.1RFC 2673, bagian 3.2 (dotted-quad)
ipv6alamat IPv6 dalam bentuk teks apa pun — lengkap, dikompresi dengan ::, atau diakhiri alamat IPv4 — 2001:db8::1. Zona (%eth0) atau panjang prefiks (/64) bukan bagian dari alamatRFC 4291, bagian 2.2
uuid32 digit heksadesimal dalam kelompok 8-4-4-4-12 yang dipisahkan tanda hubung, dalam huruf besar maupun kecil — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, bagian 3
date-timestempel waktu dengan offset — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, dengan hari yang ada dalam bulannya, dan detik kabisat hanya pada 23:59 UTCRFC 3339, bagian 5.6 (date-time)
datetanggal kalender — 2026-09-28 — yang harinya ada dalam bulan dan tahunnyaRFC 3339, bagian 5.6 (full-date)

Format hanya menilai string dan tidak yang lain: nilai dari tipe lain dinilai oleh type-nya. Format juga hanya menilai sintaks nilai — nama host tidak pernah di-resolve, URI tidak pernah diambil, mailbox tidak pernah dihubungi — sehingga pemeriksaan memberikan jawaban yang sama pada setiap build dan tidak memerlukan jaringan.

Pemeriksaan dijalankan di mana pun nilai divalidasi terhadap skemanya: parameters: milik Aggregate, values dan infra yang dibatasi oleh pilar schema: milik Component atau Feature, values dan infra per edge yang dibatasi oleh skema payload soket usesSchema:, dan setiap entri SchemaLibrary yang dijangkau skema-skema tersebut. Nama format pada pilar provides dinilai saat katalog dimuat seperti skema lainnya; nilai yang dipublikasikan sebuah Recipe tidak divalidasi terhadap pilar tersebut, sehingga tidak ada format yang diperiksa padanya. Di dalam allOf, anyOf, oneOf dan not, nilai yang gagal pada formatnya adalah nilai yang gagal pada cabang tersebut, persis seperti nilai yang gagal pada batasan lain. Nilai yang tidak sesuai ditolak dengan menyebutkan bidang, nilai, dan formatnya.

Nama di luar tabel ditolak saat skema dimuat, baik ada maupun tidak ada nilai yang mencapainya, dan penolakan tersebut mencantumkan nama-nama yang didukung — sehingga salah ketik seperti emial menjadi diagnostik, bukan batasan yang tidak memeriksa apa pun. Untuk entri SchemaLibrary, jalankan aggrega validate pada seluruh katalog untuk melihat nama yang salah: Release yang skemanya menjangkau entri tersebut juga ditolak, tetapi melaporkan library sebagai tidak ditemukan. password bukan format: bidang yang membawa materi rahasia mendeklarasikan sensitive: true sebagai gantinya.

Satu batasan berlaku untuk bentuk yang dijangkau secara tidak langsung. Ketika bentuk suatu bidang berasal dari $ref: yang membawa kata kunci lain di sampingnya (misalnya map properties:), dari then: atau else: milik when:, atau dari pointer ke properti yang dideklarasikan, format-nya diperiksa pada bidang yang dideklarasikan bentuk tersebut secara langsung dan melalui allOf — tetapi tidak di dalam cabang anyOf, oneOf, not atau cabang kondisional di dalam bentuk tersebut.

Kata kunci komposisi dan referensi

Kata kunciArtiDikompilasi menjadi JSON Schema
$refReferensi ke fragmen JSON Pointer atau entri SchemaLibrary eksternal$ref:
allOf / anyOf / oneOfKomposisi JSON SchemaKata kunci yang sama
patternPropertiesMap dengan kunci regexKata kunci yang sama
valuesTypeSingkatan untuk map bernilai bertipe (mis., “objek yang semua nilainya string”)additionalProperties: { type: <X> }

Kata kunci kontainer

Kata kunciArtiDikompilasi menjadi JSON Schema
itemsBentuk elemen arrayitems: (bentuk ringkas rekursif atau JSON Schema)
propertiesDeklarasi anak eksplisit (jarang diperlukan; biasanya implisit melalui struktur YAML)properties:
additionalPropertiesApakah properti yang tidak dideklarasikan diizinkan (false pada objek bentuk tersirat, tempat kompiler menambahkannya; pada type: object eksplisit, Anda yang menuliskannya, dan default JSON Schema sendiri, true, berlaku jika Anda tidak menuliskannya)additionalProperties:

Kata kunci khusus Aggrega

Kata kunciArti
validatePredikat templat Go per bidang yang mengembalikan boolean; false menghentikan validasi dengan validateMessage:
validateMessagePesan kesalahan yang menyertai kegagalan validate:
whenPenerapan subpohon kondisional; predikat templat Go yang menentukan apakah batasan node berlaku
sensitiveMendeklarasikan bahwa daun ini membawa materi rahasia. Dikompilasi menjadi x-aggrega-sensitive: true. Lihat “Mendeklarasikan daun sebagai sensitif” di bawah
$jsonschemaJalan keluar — sub-dokumen JSON Schema lengkap yang disematkan pada node ini
$modeAnotasi dispatch opsional untuk kasus ambigu (jarang diperlukan; lihat “Bentuk objek tersirat vs eksplisit” di bawah)

Kata kunci JSON Schema yang dipinjam ($ref, allOf, format, dll.) menggunakan sintaks yang identik dengan JSON Schema, sehingga penulis yang sudah mengenal JSON Schema langsung mengenalinya.

Kata kunci yang nilainya berupa data membawa nilai itu sebagaimana ditulis. Pemetaan atau daftar yang diberikan ke default, enum, atau const adalah nilai itu sendiri, tidak pernah skema bersarang: endpoint: { type: object, default: { host: db, port: 5432 } } menjadikan objek itu nilai default endpoint, dan mode: { type: object, const: { kind: fast } } hanya menerima objek itu persis — begitu pula mode: { const: { kind: fast } }, karena const, seperti enum, dengan sendirinya menjadikan node sebuah leaf. Hal yang sama berlaku di dalam jalan keluar $jsonschema:.

Struktur leaf bentuk ringkas

Unit penulisan adalah sebuah node leaf — sebuah field dengan dict batasan:

field_name: { type: <type>, ...constraints... }

Pola umum:

port: { type: integer, default: 8080 }
port: { type: integer, min: 1, max: 65535, default: 8080 }
identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }
log_level: { type: string, enum: [debug, info, warn, error], default: info }
name: { type: string, minLength: 1, required: true }
email: { type: string, format: email }
enabled: { type: boolean, default: false }

Setiap leaf ditulis dalam satu baris. Dict batasan memuat segala hal tentang bentuk field; struktur node induk memuat lokasi field tersebut.

Objek bersarang

Struktur objek mencerminkan penyarangan YAML. Penyarangan yang dalam dapat langsung digunakan, dengan setiap leaf tetap berada pada satu baris:

spec:
schema:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" }
auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }

Compiler menyimpulkan struktur objek dari hierarki YAML. Node perantara (di sini: primary, resources, requests, limits, auth) adalah tipe objek yang berisi turunan bersarangnya. Compiler menghasilkan blok type: object dan properties: yang eksplisit dalam JSON Schema yang telah di-resolve; penulis tidak menuliskannya.

Bentuk objek tersirat vs eksplisit

Cakupan objek dalam bentuk ringkas dapat ditulis dengan dua cara:

Bentuk tersirat — anak-anak langsung di bawah kunci induk, tanpa deklarasi type: object:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

Compiler mengenali cakupan tersebut sebagai objek karena anak-anaknya merupakan deklarasi properti. Compiler menghasilkan type: object, properties: { ... }, dan secara otomatis menyisipkan additionalProperties: false pada waktu kompilasi. Semantik penutupan merupakan bagian dari kontrak bentuk tersirat: salah ketik pada bidang yang ditulis pengembang akan gagal secara jelas.

Bentuk eksplisit — type: object dideklarasikan, properties: dirinci:

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

Compiler TIDAK menyisipkan additionalProperties: false dalam bentuk eksplisit. Penulis yang mendeklarasikan type: object memikul tanggung jawab penuh atas keputusan penutupan; bentuk eksplisit adalah sarana untuk map yang benar-benar terbuka (additionalProperties: true) dan untuk objek yang memerlukan kata kunci JSON Schema lain (patternProperties, propertyNames, unevaluatedProperties).

Kriteria penulisan: gunakan bentuk tersirat untuk objek tertutup biasa (kasus umum dalam skema katalog). Gunakan bentuk eksplisit apabila objek harus benar-benar terbuka, atau apabila skema memerlukan kata kunci JSON Schema yang tidak dimuat secara langsung oleh bentuk ringkas.

Semantik penutupan

Menurut konvensi, objek bentuk tersirat dalam bentuk ringkas bersifat tertutup: properti yang tidak dideklarasikan menghasilkan galat validasi. Kompiler secara otomatis mengeluarkan additionalProperties: false pada setiap cakupan objek bentuk tersirat. Hal ini sesuai dengan disiplin katalog bahwa salah ketik harus gagal secara jelas.

Untuk membuka sebuah objek (mengizinkan properti tambahan sembarang), gunakan bentuk eksplisit dengan additionalProperties: true:

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

Untuk pola umum “objek yang semua nilainya berbagi satu tipe” (misalnya, peta string → string untuk label), gunakan valuesType::

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type> dikompilasi menjadi additionalProperties: { type: <type> }. Pola ini cukup sering digunakan sehingga layak mendapatkan singkatan berupa satu kata kunci.

Nama tipe polos di atas adalah ejaan untuk schema: dan SchemaLibrary. Pada slot parameters: sebuah Aggregate, tuliskan nilainya sebagai kontrak — valuesType: { type: string }. Hal yang sama berlaku untuk dua kata kunci lain yang nilainya sendiri berupa kontrak, yaitu items: dan setiap entri di bawah properties:, karena deklarasi parameter dan setiap kontrak yang bersarang di dalamnya memiliki satu bentuk yang sama. Nama tipe polos di salah satu dari ketiga posisi tersebut pada slot parameter akan ditolak, dan diagnostiknya menyebutkan kontrak bersarang mana yang memuatnya. Lihat entities/aggregate.md untuk kosakata slot parameter selengkapnya.

Field wajib

Field wajib menggunakan required: true per leaf:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }

Compiler mengumpulkan semua penanda required: true dalam suatu cakupan objek dan mengeluarkannya sebagai larik required: [field1, field2] milik JSON Schema. Penanda ini berlaku di mana pun properti dideklarasikan: dalam cakupan bentuk tersirat, dan pada properti di dalam blok properties: eksplisit.

Konsumen yang menarik entri SchemaLibrary ke dalam skemanya melalui $ref: dapat menyebutkan field wajibnya dengan salah satu dari dua cara — larik required: [name1, name2] di tingkat induk di samping referensi, atau penanda required: true pada properti yang dideklarasikannya di bawah properties: di sana. Lihat cross-document-ref.md §“Sintaks required: di bawah $ref: lintas dokumen” untuk aturan lengkapnya.

Array

Array menggunakan type: array dengan items: yang menjelaskan bentuk elemennya:

tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars:
type: array
items:
name: { type: string, required: true }
value: { type: string }
valueFrom: { type: object, additionalProperties: true }
allowedHosts:
type: array
min: 1 # minItems
max: 100 # maxItems
items: { type: string, format: hostname }

Untuk kasus umum “array skalar bertipe”, bentuk inline cukup satu baris. Untuk array objek, items: memperkenalkan skema bentuk ringkas bersarang.

Kata kunci type: — skalar atau array tipe

type: menerima satu nilai tunggal (type: string) atau array tipe yang diizinkan (type: [string, integer, boolean]). Bentuk array adalah ekspresi standar JSON Schema 2020-12 untuk “field ini menerima salah satu dari beberapa tipe”:

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

Ketika type: berisi array, ruang nilainya adalah gabungan dari ruang nilai tipe-tipe yang disebutkan. Penulis skema yang menggunakan bentuk array harus menangani kedua bentuk di hilir — field type pada JSON Schema hasil resolusi berisi string atau array, dan konsumen yang menelusuri skema hasil resolusi memeriksa kedua bentuk tersebut.

Kata kunci yang dicadangkan di setiap cakupan bentuk inferensi

Dispatch bentuk inferensi mengenali sekumpulan kecil kata kunci yang memiliki makna pada tingkat kosakata bentuk ringkas: description, type, default, required, kata kunci batasan (enum, const, min, max, pattern, format, dll.), dan kata kunci khusus Aggrega (validate, validateMessage, when, sensitive). Ketika salah satu kata kunci ini muncul sebagai nama field pada cakupan objek bentuk inferensi, kompiler membaca cakupan yang melingkupinya sebagai leaf batasan, bukan sebagai objek: kata kunci tersebut dianggap sebagai batasan, bukan properti anak, dan setiap kunci lain dalam cakupan itu kemudian juga harus berupa kata kunci, sehingga kunci pertama yang bukan kata kunci ditolak sebagai kata kunci yang tidak dikenal.

sensitive perlu disebutkan secara khusus di sini, karena kata ini jauh lebih mungkin menjadi nama field nyata yang ditulis pengembang dibandingkan kata kunci khusus Aggrega lainnya. Skema yang benar-benar memerlukan properti bernama sensitive — misalnya komponen yang values-nya mengekspos flag sensitive miliknya sendiri — harus mendeklarasikan cakupan yang melingkupinya secara eksplisit, persis seperti untuk properti bernama type atau default. Bentuk eksplisit di bawah ini maupun $mode: jsonschema pada cakupan yang melingkupinya dapat mencapainya: di bawah $mode: jsonschema seluruh node dibaca sebagai JSON Schema yang ditulis langsung, tempat sensitive merupakan konten biasa, bukan kata kunci bentuk ringkas.

Untuk skema yang memerlukan properti yang dinamai menurut kata kunci yang dicadangkan (misalnya, kontrak Component dengan field description: yang ditulis pengembang, atau field type:, atau field default:), gunakan bentuk eksplisit untuk cakupan yang bermasalah:

spec:
schema:
values:
type: object
properties:
description: { type: string } # property named "description"
type: { type: string } # property named "type"
default: { type: string } # property named "default"
required: [description, type]
additionalProperties: false

Bentuk eksplisit melewati dispatch — properties: menyebutkan anak-anaknya secara eksplisit, sehingga tabrakan kata kunci tidak terjadi.

Batasan ini berlaku di setiap cakupan bentuk inferensi, secara rekursif. Objek bentuk inferensi bersarang yang berisi properti yang dinamai menurut kata kunci yang dicadangkan akan dibaca sebagai leaf batasan pada cakupan tersebut. Perbaikannya sama: ubah cakupan yang bermasalah ke bentuk eksplisit.

Referensi

Referensi meminjam $ref: dari JSON Schema secara sintaksis dan semantik:

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

Blok $defs: di dalam skema bentuk ringkas mendeklarasikan definisi yang dapat digunakan ulang. Setiap entri merupakan skema bentuk ringkas (atau JSON Schema, atau campuran). Rujuk melalui fragmen JSON Pointer #/$defs/<Name>:

Deklarasikan blok tersebut di dalam pilar yang field-nya merujuk kepadanya, di samping field-field tersebut — bukan di samping pilarnya. Blok schema: hanya menerima tiga nama pilar data pada tingkat teratasnya sendiri, sehingga $defs: yang ditulis sebagai saudara dari values: ditolak saat entitas dimuat, dengan menyebutkan kunci yang bermasalah dan himpunan pilar yang boleh dimuatnya. Pointer dituliskan #/$defs/<Name> dalam kedua kasus.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }

Untuk referensi lintas dokumen yang menargetkan entri SchemaLibrary, lihat cross-document-ref.md. Untuk ekspansi singkatan URI OCI, lihat uri-grammar.md.

Arahkan referensi ke definisi, bukan ke properti

Pointer yang menyebut entri $defs: — #/$defs/PodResources — adalah bentuk yang sebaiknya digunakan. Pointer sah di mana pun JSON Schema mengizinkannya, sehingga pointer ke properti yang dideklarasikan juga diterima dan ditegakkan, tetapi pelaporannya kurang presisi, dan perbedaannya perlu Anda ketahui sebelum menulisnya.

Field yang bentuknya berasal dari entri $defs: diperiksa per field: kegagalan dilaporkan pada jalur nilai yang benar-benar salah, dan setiap kegagalan di bawah field tersebut dilaporkan, bukan hanya yang pertama.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

cpu yang salah di sini dilaporkan pada primary.resources.requests.cpu.

Field yang bentuknya berasal dari pointer ke properti yang dideklarasikan diperiksa sebagai bagian dari dokumen secara keseluruhan. Batasannya tetap berlaku dan dokumen yang melanggarnya tetap terhenti — tetapi kegagalan dilaporkan pada field yang membawa pointer, bukan pada nilai di dalamnya, dan jika beberapa field seperti itu salah sekaligus, hanya salah satunya yang disebutkan.

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

cpu yang salah di bawah secondary dilaporkan pada secondary.resources.

Kedua cara penulisan menerima dan menolak dokumen yang sama, kecuali satu batasan pada format yang dinyatakan dalam Format bernama: melalui pointer, format di dalam cabang anyOf, oneOf atau not dari bentuk tersebut tidak diperiksa. Selebihnya, yang berbeda adalah seberapa banyak informasi yang diberikan pesan, yang paling penting di editor, tempat penanda diletakkan berdasarkan jalur tersebut. Hal yang sama berlaku untuk entri $defs: yang pointer-nya sendiri menjangkau kembali ke properti: mencapai suatu definisi melaluinya mewarisi laporan yang lebih kasar.

Bentuk kondisional melalui when:

JSON Schema 2020-12 menyatakan bentuk kondisional melalui if/then/else. Bentuk ringkas menyediakan when: sebagai singkatan yang lebih langsung: sebuah predikat templat Go yang, jika bernilai benar, menerapkan batasan lain pada node tersebut; jika bernilai salah, node diperlakukan seolah-olah batasannya tidak ada.

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

Predikat dievaluasi terhadap nilai instans milik induknya. $ merujuk ke cakupan objek di sekitarnya. Ketika architecture bernilai replication, batasan tersebut (required: true, serta tambahan replicaCount: min: 2) diterapkan di atas NodePool yang dirujuk. Ketika architecture bernilai standalone, batasan tersebut tidak aktif.

Predikat memiliki akses ke fungsi templat Go standar (Sprig). Kompiler mengompilasi when: menjadi if/then/else milik JSON Schema ditambah sebuah pembungkus untuk mengevaluasi predikat templat Go sebelum validasi dijalankan. Determinisme tetap terjaga karena predikat bersifat murni terhadap instans.

Validasi kustom per bidang melalui validate: dan validateMessage:

Beberapa batasan tidak dapat dinyatakan dengan min / max / pattern / enum. Untuk batasan tersebut, bentuk ringkas menyediakan validate: — sebuah predikat templat Go yang, jika bernilai salah, menghentikan validasi dengan galat kustom.

db_size:
type: string
pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$"
validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}'
validateMessage: "db_size must exceed 100 in its declared unit"

Predikat dijalankan terhadap nilai bidang (dapat diakses sebagai .); cakupan objek di sekitarnya adalah $. Jika predikat mengembalikan nilai salah, validasi menghasilkan galat menggunakan validateMessage: (atau pesan bawaan jika tidak disediakan).

validate: menangani kasus di luar kosakata standar JSON Schema: validasi semantik kustom (pemeriksaan format semver, konten JSON di dalam string), aturan lintas bidang dengan cakupan sempit ketika batasan suatu bidang bergantung pada bidang saudaranya, serta batasan yang tidak sepadan dengan blok assertions: penuh.

validate: berbeda dari when: dalam perannya: when: menentukan apakah batasan berlaku; validate: sendiri adalah sebuah batasan.

Untuk aturan yang benar-benar lintas bidang dengan cakupan luas, ketika tidak ada satu bidang pun yang menjadi “bidang yang divalidasi”, gunakan blok khusus assertions:. Lihat templates/assertions-block.md.

Mendeklarasikan leaf sebagai sensitif — sensitive:

Sebuah leaf values, infra, atau provides dapat mendeklarasikan bahwa datum yang dijelaskannya membawa materi rahasia:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true
description: "The credential material itself."
key:
type: string
default: value
description: "The data key the material is stored under."

sensitive: true dikompilasi menjadi kata kunci ekstensi x-aggrega-sensitive: true pada node tersebut di JSON Schema yang telah di-resolve, bersama anotasi x-aggrega-* lainnya. Compiler membacanya untuk menurunkan attachment mana dalam sebuah deployment yang menangani materi yang dideklarasikan sensitif, dan membawa fakta turunan itu pada graf hasil kompilasi.

Deklarasikan pada datum, bukan pada lokatornya. Perbedaan ini adalah inti dari kata kunci tersebut dan mudah tertukar. Materi sebuah kredensial bersifat sensitif; nama resource yang menyimpannya dan kunci data di dalam resource itu tidak — keduanya publik, dan keduanya di-render tanpa disamarkan ke setiap konsumen yang mereferensikan resource tersebut. Menandai sebuah lokator menyatakan sesuatu yang tidak benar tentangnya dan menyebarkan kesalahan itu ke semua hal di hilir yang membaca deklarasi tersebut. Pada contoh di atas, origin ditandai dan key sengaja tidak ditandai.

Pernyataan pelengkapnya — apa pun yang mengikat titik ini menangani materi rahasia, terlepas dari apa yang dideklarasikan fill tentang leaf-nya sendiri — sama sekali bukan deklarasi leaf. Itu adalah sensitive pada attachment slot; lihat entities/component.md “Attachment Slots”.

Mendeklarasikan seluruh objek sebagai sensitif

Kata kunci ini dapat diletakkan pada objek alih-alih pada skalar, dan kemudian mencakup semua yang berada di bawah objek tersebut — anak-anak objek itu sendiri, dan apa pun yang bersarang lebih dalam. Inilah deklarasi yang tepat ketika seluruh blok merupakan materi dan menandai setiap leaf secara terpisah akan membuat leaf berikutnya yang ditambahkan seseorang tidak tertandai.

Anak-anak objek harus berada dalam blok properties: eksplisit. Inilah satu-satunya tempat bentuk objek inferensi tidak berlaku, dan alasannya layak dipahami alih-alih diakali:

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

Menulis anak-anak langsung di samping penanda, seperti yang diizinkan bentuk objek inferensi di tempat lain, ditolak pada waktu kompilasi — anak pertama dilaporkan sebagai kata kunci yang tidak dikenal, dengan posisi pada kunci anak itu sendiri:

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

Penolakan ini benar, bukan keterbatasan yang perlu diakali. Sebuah node dibaca sebagai leaf batasan segera setelah membawa kata kunci bentuk ringkas, dan sensitive: adalah salah satunya — sehingga sejak titik itu setiap kunci saudara juga harus berupa kata kunci, dan password bukan kata kunci. Blok properties: adalah yang menyatakan “kunci di bawah ini adalah nama properti, bukan kata kunci tambahan”, dan ini adalah disambiguasi yang sama yang dijelaskan di Bentuk objek inferensi vs eksplisit. Membaca diagnostik tersebut sebagai “penanda tidak dapat diletakkan pada objek” adalah salah tafsir yang harus dihindari: penanda dapat diletakkan di sana, dan blok itulah cara Anda menyatakannya.

Leaf di dalam objek yang dideklarasikan tidak memerlukan penandanya sendiri. Menambahkannya tidak berbahaya dan tidak menyatakan hal baru, karena deklarasi objek sudah mencakupnya.

Apa yang tidak dilakukan kata kunci ini

Namanya mengundang asumsi yang tidak dipenuhi kata kunci ini, jadi batas atasnya dinyatakan dengan jelas:

  • Kata kunci ini tidak mengenkripsi apa pun. Ini adalah anotasi pada sebuah deklarasi, bukan mekanisme kerahasiaan.
  • Kata kunci ini tidak memvalidasi atau menolak, kecuali di tempat parameter template CloudFormation diisi. Tidak ada nilai yang diterima atau ditolak karena sebuah leaf dideklarasikan sensitif, dan tidak ada hasil build yang berubah — kecuali bahwa ketika valuesMapping milik Recipe atau FeatureRecipe CloudFormation membaca leaf yang dideklarasikan sensitif untuk mengisi parameter template bersumber, setiap literal yang diikat mapping tersebut menghentikan build, sehingga dua build yang hanya berbeda pada deklarasi tersebut dapat berakhir berbeda. Lihat A secret bound to a CloudFormation parameter would be written into the template (Rahasia yang diikat ke parameter CloudFormation akan ditulis ke dalam template).
  • Kata kunci ini tidak menjamin bahwa output hasil render bebas dari materi. Apakah sebuah artefak membawa materi bergantung pada fill mana yang dilampirkan penulis dan apa yang ditulis penulis dalam values-nya — lihat architecture/08-credential-model.md “Apa yang dijamin dan tidak dijamin compiler”. Nilai yang dideklarasikan sensitif yang diberikan penulis secara inline di-render persis seperti nilai yang tidak dideklarasikan, di mana pun build me-render-nya.
  • Kata kunci ini tidak memaksakan mekanisme pengiriman. Kata kunci ini tidak dapat mengubah nilai inline menjadi referensi store, dan tidak mempersempit apa yang diizinkan allowlist inject milik sebuah slot.
  • Kata kunci ini tidak menghentikan build, kecuali melalui penolakan CloudFormation tersebut. Pemberitahuan waktu build yang dimunculkannya, yang dijelaskan di bawah, bersifat anjuran: build berjalan hingga selesai dan menulis artefaknya. Menjadikan pemberitahuan sebagai fatal adalah pilihan organisasi, yang dinyatakan sebagai kebijakan tata kelola yang dilampirkan pada build, bukan sesuatu yang dilakukan kata kunci ini dengan sendirinya. Penolakan provider CloudFormation di atas adalah pengecualiannya: penolakan itu menghentikan build, karena literal yang ditulis ke dalam template dapat dibaca oleh siapa pun yang dapat membaca stack.
  • Kata kunci ini tidak mengubah satu byte pun hasil render pada sebagian besar target, dan pada target tersebut tidak akan pernah mengubahnya. Platform target yang memiliki konsep sensitivitasnya sendiri adalah tempat sebuah deklarasi memiliki tempat untuk mendarat; target yang tidak memilikinya tidak punya apa pun untuk diubah, secara permanen. Terraform adalah satu-satunya target pustaka standar yang memiliki primitif semacam itu: ketika input sebuah modul vendored menerima materi yang dideklarasikan sensitif oleh penulis, output hasil render mendapatkan file override yang dihasilkan yang menyatakan atribut sensitivitas milik Terraform sendiri untuk input tersebut — lihat providers/terraform.md “Input modul yang dideklarasikan sensitif”. Di tempat lain, mendeklarasikan leaf sebagai sensitif di seluruh katalog yang ada membuat setiap artefak hasil render tetap identik.

Apa yang diubahnya pada apa yang dicetak alat

Satu hal yang memang diubah oleh deklarasi adalah apa yang dicetak alat untuk dibaca manusia: output debug-nya, dan teks penolakan, yang dijelaskan di bawah. Pada permukaan debug, nilai yang dideklarasikan sensitif diganti dengan teks tetap <redacted>:

  • trace per pass yang ditulis aggrega build --trace ke .trace/;
  • blok Values: per node yang dicetak aggrega inspect untuk sebuah Aggregate;
  • blok attachment per leaf yang dicetak aggrega inspect untuk Release yang telah di-resolve.

Kuncinya selalu dipertahankan dan hanya nilainya yang diganti, sehingga pembaca tetap melihat bahwa leaf tersebut ditulis dan bahwa sesuatu disembunyikan. Leaf yang tidak dideklarasikan penulis mencetak nilainya apa adanya di samping saudara yang disembunyikan — substitusi mengikuti deklarasi dan tidak ada yang lain, sehingga field bernama password yang tidak membawa deklarasi dicetak, sedangkan field yang dideklarasikan bernama key tidak.

Sebuah deklarasi menjangkau setiap leaf di bawahnya, dan menjangkau ketiga permukaan dengan cara yang sama. Ketika deklarasi berada pada sebuah objek, setiap nilai yang bersarang di dalam objek itu juga disembunyikan, pada kedalaman berapa pun — deklarasi objek menamai semuanya, sehingga menyembunyikannya tidak mengklaim apa pun yang tidak ditulis penulis. Pencocokan dilakukan pada segmen path utuh, bukan pada teks, sehingga saudara yang namanya hanya diawali nama yang dideklarasikan tidak tersentuh: mendeklarasikan dbPassword tidak menyembunyikan dbPasswordHint.

Penyembunyian pada trace dapat dimatikan untuk satu build, ketika nilai yang disembunyikan justru yang sedang di-debug: aggrega build --trace --trace-unredacted menulis nilai-nilai tersebut ke dalam file trace dan menandai setiap file itu dengan header yang menyatakannya. Ini adalah pilihan saat pemanggilan tanpa pengaturan konfigurasi, hanya berlaku pada trace, dan didokumentasikan di cli/aggrega-build.md “Menampilkan nilai yang disembunyikan”. Tata letak aggrega inspect memiliki opsinya sendiri, --unredacted, yang didokumentasikan di cli/aggrega-inspect.md “Menampilkan nilai yang disembunyikan”.

Batas-batas perilaku tersebut lebih penting daripada perilaku itu sendiri.

Artefak yang dirender tidak pernah disamarkan. Semua yang berada di bawah dist/ dihasilkan persis seperti yang diproduksi oleh proses render, karena itulah yang di-deploy: placeholder yang ditulis ke dalam sebuah manifest akan menjadi deployment yang rusak, bukan deployment yang terlindungi. Penyamaran mencakup apa yang dicetak oleh alat, tidak pernah apa yang ditulisnya. Membaca deklarasi sebagai janji bahwa dist/ aman untuk dipublikasikan adalah satu-satunya salah tafsir yang harus dihindari — batas di atas tidak berubah, dan dist/ tetap sesensitif attachment-nya yang paling banyak membawa materi.

Ada satu hal yang dapat ditambahkan deklarasi ke artefak yang dirender, dan itu bukan penyamaran: jika suatu target memiliki primitif sensitivitasnya sendiri, deklarasi dirender ke dalamnya. Nilainya tetap ditulis secara utuh — tidak ada yang ditahan atau diganti — dan yang diperoleh artefak adalah penanda milik target itu sendiri di sampingnya, sehingga perkakas target dapat memperlakukan nilai tersebut sebagaimana dideklarasikan oleh penulis. Terraform adalah target yang menyediakannya saat ini, dan apa yang dijamin maupun tidak dijamin oleh atributnya dijelaskan di providers/terraform.md “Declared-sensitive module inputs”. Penanda semacam itu hanya ikut jika identitas nama yang dirender dipulihkan dari deklarasi itu sendiri; jika sebuah templat menciptakan nama tersebut, penanda tidak ada alih-alih diperkirakan, karena menandai nilai yang tidak dideklarasikan penulis akan menyatakan sesuatu yang keliru tentangnya. Jika templat tersebut adalah valuesMapping — milik sebuah Recipe, atau milik FeatureRecipe dari sebuah Feature yang dipasang pada suatu komponen — build akan menyatakannya, seperti dijelaskan di bawah.

Penyamaran menjangkau apa yang dinamai oleh deklarasi, ditambah apa yang terlihat dibaca oleh templat. Leaf yang dideklarasikan dalam pilar values atau infra, dan kunci pengiriman yang membawa materi dari kunci provides yang dideklarasikan sensitif, keduanya diidentifikasi berdasarkan nama dan ditahan. Nilai yang dihitung oleh templat berada di bawah kunci yang tidak dideklarasikan siapa pun, sehingga yang mengidentifikasinya adalah referensi yang ditulis penulis: dalam trace, entri locals: atau field source: yang templatnya membaca leaf yang dideklarasikan sensitif akan ditahan, demikian pula entri locals: yang membaca sibling yang sudah ditahan. Pembacaan ini sengaja dibuat konservatif — menjangkau seluruh objek berarti menjangkau setiap leaf yang dideklarasikan di bawahnya, dan templat yang meneruskan seluruh datanya menjangkau semuanya — sehingga referensi yang tidak dapat diselesaikan akan ditahan alih-alih dicetak.

Dokumen yang dirender ditampilkan sebagai render ulang, dan hal itu dinyatakan. Workload hasil parsing dalam trace adalah dokumen yang diproduksi oleh templat Recipe: tidak ada apa pun di dalamnya yang mencatat dari deklarasi mana setiap karakter berasal, sehingga tidak ada kunci tempat substitusi dapat dilakukan di dalamnya, dan memulihkan tautan itu field demi field berarti memeriksa konten suatu nilai — yang tidak dilakukan oleh compiler. Yang ditampilkan trace sebagai gantinya adalah templat workload: yang sama yang dievaluasi lagi terhadap konteks yang data berdeklarasi sensitifnya sudah terbaca sebagai teks pengganti, diumumkan dalam entri workload_note di samping dokumen. Karena templat melihat string di tempat sebelumnya ada string, render ulang mempertahankan bentuk dokumen yang dihasilkan dan teks pengganti menempati posisi datum yang ditahan itu sendiri. Dua perbedaan tetap ada dan catatan tersebut menyatakan keduanya: templat yang bercabang berdasarkan konten suatu nilai akan merender secara berbeda terhadap teks pengganti, dan datum yang tidak dinamai oleh sumbu tersebut diteruskan tanpa perubahan. Ini adalah tampilan debugging dari apa yang dirender, tidak pernah salinannya.

Nilai node yang dikonsumsi ditahan berdasarkan deklarasi node tersebut, pada kedua permukaan tempat edge membawanya. Tampilan edge uses mereproduksi apa yang dipublikasikan oleh komponen target, sehingga skema target itu sendiri yang mengaturnya: kunci provides yang dideklarasikan sensitif oleh target ditahan pada trace konsumen meskipun konsumen tidak mendeklarasikan apa pun. Jika blok inject milik edge itu sendiri merutekan kunci tersebut ke kunci pengiriman pada komponen konsumen, kunci pengiriman itu juga ditahan — aturan yang sama yang diikuti oleh pemetaan inject milik attachment, dengan membaca deklarasi yang sama, sehingga kedua pengkabelan tidak dapat saling bertentangan. Tata letak aggrega inspect menampilkan pilar milik node itu sendiri dan attachment-nya, bukan nilai yang dipublikasikan oleh node yang dikonsumsi, sehingga tidak ada apa pun di sana yang membawa tampilan lintas node untuk ditahan.

Attachment yang ditulis pada suatu koneksi ditahan berdasarkan deklarasi Feature miliknya sendiri, pada setiap permukaan yang menampilkannya. Trace menampilkannya di bawah tampilan edge uses milik koneksi tersebut, di .context.uses.<alias>.features.<slot>, dan aggrega inspect mencetaknya di bawah baris koneksi dalam Release yang telah di-resolve. Pada keduanya, leaf values atau infra yang dideklarasikan sensitif oleh Feature-nya ditahan persis seperti pada Feature yang sama yang dipasang langsung pada komponen, dan pada trace, kunci dari provides hasil resolve milik attachment yang dideklarasikan sensitif oleh Feature juga ditahan. Tipe, versi, label, serta setiap leaf dan kunci provides yang tidak dideklarasikan dicetak apa adanya, sehingga locator yang dipublikasikan tetap dapat dibaca di samping materi yang ditunjuknya. Slot yang mendeklarasikan sensitive: true, pada komponen atau pada socket, menandai attachment sebagai penangan materi rahasia dan tidak menahan leaf apa pun atas inisiatifnya sendiri — leaf mana yang ditahan adalah hak Feature untuk mendeklarasikannya.

Proyeksi yang dapat dibaca mesin bersifat apa adanya berdasarkan kontrak, dan memerlukan penanganan yang sama seperti berkas asalnya. aggrega inspect --raw menghasilkan entitas persis seperti yang ditulis, dan aggrega inspect --output yaml mereproduksi entitas yang ditulis untuk setiap jenis, termasuk Release. Keduanya tidak mensubstitusi apa pun, dan hal itu disengaja: inilah keluaran yang di-parse oleh skrip dan dibandingkan oleh diff, sehingga keluaran yang diam-diam menahan sebagian dirinya akan salah merepresentasikan masukan yang diklaim direproduksinya dan merusak round-trip yang diandalkan oleh konsumennya. Mendeklarasikan leaf sebagai sensitif tidak cukup untuk menjauhkannya dari keluaran tersebut: salurkan, simpan, dan bagikan keluaran itu sebagaimana Anda memperlakukan Aggregate dan Release itu sendiri.

Graf hasil kompilasi adalah satu-satunya proyeksi yang dapat dibaca mesin yang memang menahan nilai, di mana pun graf itu diberikan. --ir-graph, pada aggrega inspect, aggrega validate, dan aggrega build, menulis graf yang di-resolve oleh proses tersebut sebagai JSON di samping apa pun yang sudah dihasilkan perintah, dan aggrega/irGraph milik daemon menjawab editor dengan graf yang sama; pada masing-masing, nilai yang dideklarasikan sensitif oleh penulis diganti persis seperti pada tata letak yang dapat dibaca. --unredacted di samping --ir-graph mencetak nilai-nilai tersebut, demikian pula field unredacted pada permintaan ke daemon. Jadi, graf yang dibaca dari perintah dan graf yang dibaca melalui protokol daemon adalah dokumen yang sama dengan aturan penanganan yang sama, dan pipeline atau klien yang membutuhkan nilai yang ditulis harus memintanya.

Apa yang dinyatakan sebuah penolakan tentang nilai yang dideklarasikan

Penolakan yang dimunculkan oleh templat yang membaca nilai yang dideklarasikan sensitif oleh penulis tidak membawa nilai tersebut. Ketika sebuah templat menghentikan build — asersi yang memanggil fail, ekspresi yang tidak dapat dievaluasi, keluaran yang tidak terbaca sebagai dokumen yang harus dihasilkan templat — dan salah satu referensinya menjangkau datum yang dideklarasikan sensitif, apa yang dilaporkan berasal dari evaluasi templat yang sama untuk kedua kalinya, terhadap konteks tempat setiap datum yang dideklarasikan sensitif sudah terbaca <redacted> — kecuali templat berhenti pada kalimat yang ditulisnya sendiri secara lengkap, yaitu kasus pertama di bawah:

assertion failed: the admin password <redacted> must be supplied as a reference
  • fail yang kalimatnya ditulis lengkap di dalam templat dilaporkan sebagaimana ditulis. Ketika panggilan yang menghentikan build adalah fail dengan satu string berkutip — fail "…", tanpa apa pun yang di-pipe ke dalamnya dan tanpa apa pun yang disusun ke dalam kalimatnya — penolakan membawa kalimat tersebut apa pun isi nilainya dan cabang mana pun yang mengarah ke panggilan itu, karena kalimat itu tidak mengutip apa pun yang dibaca templat: asersi yang menolak asal dengan bentuk yang salah menampilkan penjelasannya sendiri tentang bentuk tersebut. Kalimat yang dibangun dengan cara lain — printf, sebuah field, sebuah variabel, nilai yang di-pipe ke fail — dilaporkan menurut kasus-kasus berikut.
  • Jika evaluasi kedua gagal pada ekspresi yang sama dengan alasan yang sama, kegagalan itulah yang dilaporkan. Kalimat penulis sendiri tetap utuh dengan <redacted> di tempat nilai tersebut berada, dan nilai yang dienkode, dikutip, atau ditransformasikan dengan cara lain oleh templat juga ditahan, karena penggantian terjadi sebelum transformasi.
  • Jika tidak, penolakan menyebutkan ekspresi yang gagal dan menyatakan bahwa teksnya ditahan. Itu adalah templat yang perilakunya bergantung pada isi nilai — templat tersebut mengambil cabang lain, atau gagal di tempat lain, terhadap teks pengganti — sehingga tidak ada yang disusunnya yang dapat ditampilkan. Agar penolakan semacam itu menjelaskan dirinya sendiri, tuliskan kalimatnya secara lengkap dalam panggilan fail, seperti yang dijelaskan kasus pertama. Penolakan tetap menghentikan build, dan kodenya tetap dipertahankan.
  • Workload hasil render yang ditolak oleh skema Workload dirumuskan dari skema. Field dokumen tidak membawa tautan kembali ke data yang dibaca templatnya, sehingga jika templat tersebut membaca datum yang dideklarasikan sensitif, setiap temuan yang dapat mengutip nilai akan menyatakan batasannya sebagai gantinya, dengan <redacted> di tempat nilai dan pemberitahuan yang menjelaskan alasannya. Tidak ada saran yang diturunkan dari nilai yang diberikan, dan temuan yang tidak mengutip nilai — kunci yang hilang, kunci yang tidak diterima oleh Workload — terbaca seperti biasa:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)
  • Input with dari sebuah langkah pipeline yang ditolak oleh kontrak input yang dideklarasikan langkah tersebut dirumuskan dari kontrak jika templat with membaca datum yang dideklarasikan sensitif: setiap posisi yang gagal dalam input dan kata kunci skema yang menolaknya, diikuti pemberitahuan yang menjelaskan alasannya, dan tidak satu pun yang dibawa input.
  • Penolakan yang menyebutkan koordinat source: dirumuskan dari apa yang dihasilkan oleh hal yang tidak dideklarasikan jika templat source: menghasilkan koordinat tersebut dengan membaca datum yang dideklarasikan sensitif — sumber tidak ada di lockfile atau cache, arsip yang di-cache tidak cocok dengan yang dicatat lockfile, atau pin yang dicatat di samping entitas tidak sesuai dengan lockfile. Setiap baris yang dicetak penolakan semacam itu menyebutkan koordinat yang digunakan pencarian, sehingga penolakan menyebutkan sumber berdasarkan url-nya dan versi atau referensi yang diminta — sejauh telah membacanya — dengan <redacted> menggantikan setiap koordinat yang dihasilkan templat semacam itu, dan menyatakan bahwa alasannya ditahan. Penolakan tetap mempertahankan kodenya dan remediasi yang diberikan build untuk kode tersebut:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template produced

Apa yang dianggap dideklarasikan adalah apa yang disebutkan oleh deklarasi, pada setiap bagian konteks yang dapat dibaca templat: values dan infra milik komponen itu sendiri, Features yang terpasang padanya dan pada setiap koneksinya, kunci pengiriman yang membawa materi yang dideklarasikan, kunci provides yang dideklarasikan sensitif oleh Component-nya, setiap entri dari daftar yang dibawa konteks, sebagaimana dijelaskan di bawah, dan entri locals: yang dihitung dari salah satunya. Templat yang tidak membaca satu pun dari semua itu melaporkan persis seperti jika tidak ada deklarasi di mana pun, byte demi byte, sehingga hanya penolakan yang dimunculkan oleh templat yang membaca nilai yang dideklarasikan yang dilaporkan secara berbeda. Pembacaannya sama dengan yang digunakan trace, dibaca dari referensi yang dituliskan templat: menjangkau seluruh objek berarti menjangkau setiap leaf yang dideklarasikan di bawahnya, sehingga dapat menahan teks yang tidak memuat nilai. Templat yang meneruskan seluruh datanya sekaligus — titik atau $ tanpa apa pun setelahnya, yang diteruskan ke fungsi seperti toJson, dicetak, atau diserahkan ke templat yang dipanggilnya berdasarkan nama — membaca setiap nilai yang dideklarasikan di dalamnya, sehingga penolakannya dilaporkan dengan cara yang sama; di dalam badan range atau with, titik adalah nilai yang diiterasi atau dinamai badan tersebut, dan meneruskannya hanya membaca apa yang dimuat nilai itu. Tidak ada di sini yang bergantung pada --trace-unredacted: flag tersebut hanya menjangkau file trace, dan penolakan terbaca sama dengan maupun tanpa flag tersebut.

Nilai yang dideklarasikan ditahan di mana pun ia berada, termasuk di dalam daftar. Entri-entri dari satu daftar diatur oleh entitas yang berbeda, dan setiap entri ditahan berdasarkan deklarasi entitasnya sendiri. Pada tampilan .boundary yang dibaca FeatureRecipe berlingkup boundary, setiap koneksi yang tercantum di internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges, dan cross_boundary_uses_edges membawa provides yang diterbitkan targetnya, yang ditahan jika Component milik target mendeklarasikan kunci itu sensitif, dan setiap entri feature_attachments membawa infra milik lampiran tersebut, yang ditahan jika Feature-nya mendeklarasikan leaf itu. Pada konteks Feature yang dilampirkan ke sebuah komponen, setiap entri .context.used_by membawa apa yang diterbitkan komponen penghubung, yang ditahan jika Component milik komponen penghubung mendeklarasikan kunci itu. Kunci yang sama pada entri yang entitasnya tidak mendeklarasikan apa pun dikutip apa adanya, dan entri locals: yang dihitung dari entri yang ditahan ikut ditahan. Mengiterasi sebuah daftar, atau menjangkau salah satu entrinya melalui index, berarti membaca seluruh daftar, sehingga dihitung sebagai membaca apa yang dibawa setiap entri:

error calling fail: target secret_ref "<redacted>" must start with ref-

Hal itu menjangkau teks penolakan yang dimunculkan build. Apa yang diberitahukan kepada penyedia tentang bagian inputnya yang berasal dari nilai yang dideklarasikan — nilai yang dihasilkan valuesMapping, dokumen workload: yang dirender, setiap entri artifacts:, setiap field dari entri omits: — tidak memperhitungkan nilai yang dibaca dari dalam daftar, sehingga penanganan penyedia sendiri atas nilai yang dideklarasikan, termasuk penolakan CloudFormation atas literal terikat yang dijelaskan di atas, tidak menjangkau nilai semacam itu.

Beberapa penolakan berada di luar ketentuan ini. Teks yang ditulis plugin — penolakan milik provider atau langkah pipeline itu sendiri — adalah kalimat plugin, dibawa sebagaimana ditulis plugin. Templat yang dievaluasi di luar asersi build dan render-nya — interpolasi parameter dan pemeriksaan parameter dalam Aggregate, templat when: dan validate: milik skema, serta resolusi koordinat source: yang mencatat pin-nya — melaporkan kegagalannya sebagaimana kegagalan itu terjadi.

Peringatan build untuk nilai yang dikirim sebagai literal

Build mencetak satu peringatan per kunci pengiriman yang membawa materi yang dideklarasikan sensitif sebagai nilai literal. Peringatan ini muncul ketika blok inject milik sebuah lampiran merutekan kunci provides yang dideklarasikan sensitif oleh Feature lampiran tersebut ke kunci pengiriman komponen yang mengonsumsinya, dan nilai tersebut benar-benar dikirim:

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

Tiga hal tentang peringatan ini disengaja.

Peringatan ini melaporkan bagaimana sebuah nilai dikirim, bukan bahwa ada sesuatu yang salah. Mengirim literal sering kali merupakan satu-satunya hal yang diterima target, dan ada satu keluarga lampiran yang dibuat persis untuk melakukan itu. Peringatan ini memberi tahu penulis nilai mana yang mengambil rute tersebut dan di mana, sehingga pilihan itu terlihat alih-alih tersirat; peringatan ini tidak menyatakan bahwa pilihan itu sebuah kesalahan.

Ini adalah peringatan dan tidak pernah penghentian. Build berhasil dan menulis artefaknya tanpa perubahan. Organisasi yang ingin agar kredensial yang dikirim sebagai literal menggagalkan build menyatakannya sebagai kebijakan tata kelola atas build, karena di situlah penolakan semestinya berada — aturan yang harus dilanggar oleh sebagian deployment bukanlah default kompiler.

Peringatan ini ditentukan dari pengkabelan, tidak pernah dari nilai. Peringatan membaca sensitivitas yang dideklarasikan skema ditambah pengiriman yang ditulis penulis. Tidak ada nilai yang diperiksa, sehingga sebuah field tidak pernah ditebak sebagai kredensial dari nama atau isinya, dan nilai yang tidak dideklarasikan yang kebetulan memuat kata sandi tidak memunculkan apa pun.

Dua kasus sengaja tetap diam. Kunci pengiriman yang kunci provides rujukannya tidak memublikasikan apa pun tidak mengirim literal dan tidak melaporkan apa pun — peringatan mengikuti pengiriman yang benar-benar terjadi. Dan slot yang allowlist inject-nya kosong menyerahkan pengiriman kepada Recipe, sehingga penulis tidak menulis kunci pengiriman yang perlu dilaporkan dan tidak ada yang perlu ditindaklanjuti.

Peringatan ini memiliki kelasnya sendiri, dengan kodenya sendiri, dan --no-unsupported-field-warnings tidak membungkamnya: flag tersebut mencakup pemberitahuan fidelitas target, yang merupakan penilaian berbeda yang dibungkam karena alasan berbeda. Peringatan ini juga menjangkau editor, tempat ia muncul sebagai masalah pada Aggregate, setiap kali language server berjalan dengan --build-on-inspect (atau kunci konfigurasi serve.build_on_inspect) diaktifkan. Pengaturan itu nonaktif secara default demi konsistensi dengan aggrega inspect: perintah terminal tidak pernah mencapai tahap rendering saat menginspeksi graf, sehingga tidak memunculkan peringatan semacam itu juga, dan inspeksi editor yang juga tidak memunculkannya menunjukkan kepada Anda hal yang sama dengan terminal. Mengaktifkan pengaturan tersebut adalah cara Anda meminta lapisan tambahan dari editor, dan tidak ada yang ditulis ke disk saat Anda melakukannya — tahap tersebut berjalan dan artefaknya dibuang. Pengaturan ini menambahkan peringatan yang dimunculkan build saat rendering, dan tidak satu pun pemeriksaan yang menghentikan build. Setiap masalah yang dipublikasikan menyebutkan lapisan yang memunculkannya, sehingga editor dapat memisahkan peringatan ini dari yang dilaporkan tahap resolusi dan analisis.

Peringatan build untuk nilai yang dirender tanpa tanda oleh sebuah mapping

Sebuah build mencetak satu peringatan untuk setiap leaf values yang dideklarasikan sensitif yang penandaannya tidak dapat dibawa oleh render selama penulis masih memegang kendali atasnya. Peringatan ini muncul pada render dari sebuah source: yang nilainya merupakan keluaran sebuah valuesMapping — milik sebuah Recipe, atas leaf yang dideklarasikan oleh Component-nya, atau milik FeatureRecipe dari sebuah Feature yang dilampirkan pada sebuah komponen, atas leaf yang dideklarasikan oleh Feature tersebut. Kunci keluaran mapping adalah rekaannya sendiri, sehingga tidak ada deklarasi yang menyebut satu pun darinya dan target tidak menerima penandaan per kunci untuk leaf tersebut:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

Baris tersebut menyebut leaf pada koordinat yang ditulis penulis serta Recipe atau FeatureRecipe yang mapping-nya menjadi gerbang penggabungan, karena deklarasi dan mapping ditulis dalam dua entitas yang berbeda; baris sebuah lampiran diawali dengan nama tempat lampiran itu dilampirkan, sehingga dua lampiran dari satu Feature pada satu komponen dapat dibedakan. Menghapus mapping adalah kendalinya: tanpa mapping, nilai yang diterima render source dikunci dengan path leaf yang dideklarasikan, dan penandaan ikut bersamanya. Render khusus artefak dan render khusus workload tetap diam, karena keduanya sama sekali tidak memberikan peta nilai kepada targetnya, demikian pula Feature yang dilampirkan pada sebuah boundary, yang dirender terhadap pilar values yang kosong — batas di atas bersifat permanen di sana, dan sebuah peringatan tidak akan menyebut apa pun yang dapat dilakukan. Seperti peringatan untuk nilai yang dikirim sebagai literal, ini adalah peringatan dan tidak pernah penghentian, tidak mengubah satu byte pun yang dirender, merupakan kelasnya sendiri dengan kodenya sendiri, sensitivity-not-conveyed, dan --no-unsupported-field-warnings tidak membungkamnya. Peringatan dan keluaran linter memuat bentuk lengkapnya.

Di mana deklarasi dibaca, dan di mana tidak

Kata kunci dibaca pada node tempatnya berada, lalu pembacaan mengikuti setiap jalur yang memungkinkan sebuah deklarasi mencapai datum tersebut: peta properti bersarang, setiap cabang komposisi, dan target sebuah $ref. Cabang dan target referensi sama-sama dikomposisikan ke properti yang membawanya, sehingga deklarasi yang ditemukan melalui salah satunya dikumpulkan untuk properti tersebut; hanya penurunan properties yang memperpanjang path.

Sebuah penanda dibaca baik ketika berada di samping salah satu kata kunci tersebut maupun di dalam apa yang dicapai kata kunci itu, sehingga dua bentuk berikut tidak memerlukan penempatan yang disengaja:

  • Di samping sebuah $ref, atau di dalam target referensi. Penanda pada leaf yang merujuk mendeklarasikan leaf tersebut. Penanda di dalam skema yang dirujuk juga dikumpulkan untuk leaf yang merujuk, pada path leaf itu ditambah rantai di bawahnya — tidak pernah pada path di dalam definisi, tempat tidak ada nilai yang ditulis.
  • Di samping kata kunci komposisi (allOf / anyOf / oneOf), atau di dalam properties milik sebuah cabang. Sebuah cabang dikomposisikan ke objek yang membawanya, sehingga setiap cabang ditelusuri — termasuk cabang kondisional dari node yang ditulis sebagai JSON Schema — dan deklarasi di dalam salah satunya dikumpulkan pada path properti yang mengomposisikan ditambah rantainya.

Satu bentuk memang memerlukan penanda yang ditempatkan secara sengaja:

  • Pada leaf array itu sendiri, bukan pada tipe elemen items-nya. Array yang elemennya membawa materi dideklarasikan sensitif pada array, karena tipe elemen bukan peta properti dan tidak ditelusuri.

parameters: adalah kosakata yang berbeda

sensitive bukan bagian dari kosakata kontrak bertipe parameters:. Aggregate yang mendeklarasikannya pada sebuah entri parameter ditolak saat Aggregate dimuat, dengan diagnostik amplop dokumen yang melaporkan unexpected property: "sensitive" (properti tak terduga: “sensitive”) yang diposisikan pada kunci yang bermasalah itu sendiri — perlakuan yang sama dengan yang diterima setiap kunci di luar kosakata tersebut, karena kontrak parameter adalah objek tertutup.

Asimetri ini disengaja: sumbu sensitivitas mencakup tiga pilar data yang dideklarasikan oleh entitas katalog, sedangkan parameter adalah masukan kontrak lingkungan, bukan leaf pilar. Mengangkat materi kredensial melalui parameter didokumentasikan di architecture/08-credential-model.md “Legacy charts that demand a formatted string”, yang menjelaskan kompromi yang dibuat oleh jalur tersebut.

Komposisi dengan allOf, anyOf, oneOf

Kata kunci komposisi berfungsi seperti dalam JSON Schema:

# Inherit and extend
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, required: true }
username: { type: string, default: app_user }
password: { type: string, required: true }

Compiler menghasilkan kata kunci komposisi yang sama dalam JSON Schema yang telah di-resolve. Setiap entri penyusun dapat berupa bentuk ringkas, JSON Schema, atau referensi $ref:. Pencampuran di dalam satu komposisi didukung.

Jalan keluar — $jsonschema:

Untuk kasus di luar kosakata bentuk ringkas ($dynamicRef, unevaluatedProperties, komposisi not: yang dalam, tipe rekursif), setiap node dapat beralih ke JSON Schema penuh:

values:
architecture: { type: string, enum: [standalone, replication] }
some_complex_field:
$jsonschema: |
type: object
unevaluatedProperties: false
allOf:
- $ref: "#/$defs/Foo"
- not:
required: [conflicting_field]
patternProperties:
"^x-": { type: string }
$defs:
Foo:
type: object
properties:
name: { type: string }

Blok $jsonschema: berisi YAML JSON Schema; compiler memperlakukannya sebagai penerusan transparan — kontennya langsung masuk ke dokumen JSON Schema hasil resolusi pada posisi node tersebut. Validasi, pelaporan galat, dan perkakas semuanya bekerja pada dokumen hasil resolusi; jalan keluar ini semata-mata merupakan kemudahan penulisan.

Cabang not: dapat membawa description: yang menyatakan mengapa bentuk yang dikecualikannya ditolak. Nilai yang cocok dengan cabang tersebut kemudian ditolak dengan deskripsi itu sebagai alasannya, dicetak dalam satu baris, menggantikan kata-kata generik “not allowed here (tidak diizinkan di sini)” — jadi tuliskan sebagai kalimat yang seharusnya dibaca oleh penulis nilai yang ditolak. Hanya deskripsi yang ditulis pada cabang not: itu sendiri yang digunakan; deskripsi pada entri $defs yang hanya dirujuk oleh cabang tersebut tidak digunakan.

Setiap node di dalam blok dibaca sebagai JSON Schema, dan kata kunci bentuk ringkas yang ditulis di sana mempertahankan makna ringkasnya (min: 3 pada string tetap berarti panjang minimum). $ref di dalam blok di-resolve sama seperti di luarnya: #/$defs/Foo menunjuk entri di $defs: milik pilar, sehingga contoh mendeklarasikan Foo di sana, dan referensi yang menunjuk entri yang tidak dideklarasikan siapa pun ditolak saat entitas dimuat. $dynamicRef di-resolve terhadap $dynamicAnchor, sehingga bentuk rekursif dapat ditulis; nilai yang gagal jauh di dalam rekursi dilaporkan pada field yang memuatnya — tree.children, untuk name yang salah dua tingkat di bawah dalam pohon yang item children-nya adalah { $dynamicRef: "#node" }.

Satu batasan berlaku untuk unevaluatedProperties dan unevaluatedItems. Jika ditulis pada node yang juga membawa referensi, kata kunci komposisi (allOf, anyOf, oneOf), kondisi, atau skema dependen, keduanya dimuat tetapi tidak ditegakkan — dan unevaluatedItems juga tidak ditegakkan di samping contains. Dalam contoh di atas, unevaluatedProperties: false berada di samping allOf, sehingga { name: n, extra: 1 } diterima meskipun baik Foo maupun patternProperties tidak mendeklarasikan extra.

Jalan keluar $jsonschema: berlaku per node, bukan per dokumen. Sebuah skema dapat menggunakan bentuk ringkas untuk bagian yang sederhana, jalan keluar JSON Schema untuk satu field yang kompleks, dan $ref: untuk bentuk yang dipakai bersama — semuanya dalam satu dokumen.

Mencampur bentuk ringkas dan JSON Schema dalam satu dokumen

Bentuk ringkas dan JSON Schema dapat dicampur secara bebas di batas node mana pun. Aturan dispatch ditentukan oleh bentuk konten:

  • Node yang berisi $jsonschema: diperlakukan sebagai JSON Schema (jalan keluar).
  • Node yang berisi kata kunci tingkat atas bergaya JSON Schema (type:, properties:, additionalProperties:, if:, dll.) diperlakukan sebagai JSON Schema (bentuk eksplisit).
  • Node yang hanya berisi entri nama-properti → skema-anak (tanpa kata kunci yang dicadangkan JSON Schema) diperlakukan sebagai bentuk ringkas (bentuk tersimpulkan).
  • Node yang hanya berisi $ref: adalah passthrough referensi.
  • Node dengan allOf: / anyOf: / oneOf: adalah komposisi; setiap entri di-dispatch secara independen.

Untuk leaf bentuk ringkas, pola standarnya adalah field_name: { type: ..., constraints... } — sebuah map YAML yang berisi kosakata bentuk ringkas yang dikenal. Dispatch mengenali dict batasan dari kunci-kuncinya.

Untuk kasus ambigu yang jarang terjadi (misalnya, skema bentuk ringkas dengan field yang secara harfiah bernama type yang akan ditafsirkan oleh dispatch bentuk tersimpulkan sebagai kata kunci JSON Schema), bentuk eksplisit adalah perbaikan kanonisnya — lihat “Kata kunci yang dicadangkan di setiap cakupan bentuk tersimpulkan” di atas.

Mengimpor kontrak dari file — $import:

Kontrak tidak harus berada di dalam entitas yang mendeklarasikannya. $import: menyebutkan file tempat kontrak itu dibaca:

spec:
schema:
$import: ./contracts/api-server.schema.yaml

Seluruh spec.schema kemudian berasal dari file tersebut, yang ditulis persis seperti blok yang digantikannya — pilar di tingkat teratas, YAML bentuk ringkas atau JSON Schema di bawahnya:

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

Satu pilar dapat diimpor tersendiri, dengan pilar-pilar saudaranya ditulis secara inline di sampingnya:

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

Bentuk yang sama berlaku pada valueSchema: dan infraSchema: dari soket usesSchema:.

Aturan yang mengaturnya:

  • $import: adalah satu-satunya kunci pada posisi tempat ia muncul. Kunci saudara yang ditulis di sampingnya ditolak, alih-alih salah satu dari keduanya dibuang.
  • Path relatif dibaca terhadap direktori yang memuat file entitas yang mendeklarasikannya, tidak pernah terhadap direktori tempat build dijalankan — basis yang sama yang digunakan oleh valuesMapping:, workload: dan artifacts:. Path tersebut harus tetap berada di dalam direktori itu, karena setiap file yang dibawa oleh publikasi entitas diambil dari sana: path yang keluar dari direktori itu, atau path absolut, menyebutkan file yang tidak akan ikut berpindah bersama entitas dan ditolak — lihat A path names content outside the entity’s own directory (Path menyebutkan konten di luar direktori entitas itu sendiri). Skema yang digunakan bersama oleh beberapa entitas seharusnya berada di SchemaLibrary, dirujuk dengan $ref:.
  • File yang diimpor ikut berpindah bersama entitas. Entitas yang dipublikasikan membawa setiap file yang diimpor oleh skemanya, termasuk setiap file dalam sebuah rantai, sehingga salinan yang diambil dari registry membaca kontrak yang sama dan memvalidasi nilai-nilai yang ditulis berdasarkan kontrak tersebut — lihat aggrega push.
  • File yang diimpor memuat konten skema, bukan dokumen entitas. File yang kontennya bukan map YAML ditolak, dengan menyebutkan file tersebut.
  • File yang diimpor dapat berupa satu $import: tunggal, yang di-resolve secara rekursif; rantai yang kembali ke file yang sedang dibaca ditolak, dengan menyebutkan rantai tersebut.

Impor dibaca saat entitas dimuat, sehingga setiap permukaan yang membaca entitas tersebut melihat kontrak yang sama: aggrega validate, build, aggrega push, aggrega inspect, dan editor. File yang tidak dapat dibaca, atau konten yang bukan skema, ditolak pada saat itu alih-alih membiarkan kontrak tidak ditegakkan — dan push menolaknya sebelum apa pun dipublikasikan.

$import: dan $ref: tidak dapat saling menggantikan. $import: menyebutkan file dan menggantikan seluruh konten; $ref: menyebutkan entri SchemaLibrary berdasarkan identitas dan melakukan komposisi pada node mana pun. Nilai $import: yang memuat identitas library atau host registry ditolak dengan arahan ke $ref:. Lihat cross-document-ref.md.

Namespace ekstensi Aggrega — x-aggrega-*

Bentuk ringkas mengenali setiap kata kunci berawalan x-aggrega- sebagai ekstensi khusus Aggrega. Namespace ini terbuka: anotasi baru masuk ke katalog tanpa perubahan kosakata per kata kunci. Penulis yang menulis x-aggrega-selector, x-aggrega-narrowed-from, atau anotasi di masa mendatang akan menempatkan kontennya pada cakupan yang tepat dalam JSON Schema hasil resolusi tanpa ditolak pada waktu kompilasi.

Awalan namespace itu penting: salah ketik seperti x-agrega-source (kurang satu g) TIDAK dikenali sebagai kata kunci ekstensi dan akan ditolak oleh semantik objek tertutup pada cakupan bentuk inferensi. Cakupan awalan ini berfungsi sebagai jaring pendeteksi salah ketik bagi permukaan anotasi katalog.

Anotasi x-aggrega-* tertentu dihasilkan oleh compiler pada titik-titik yang sudah diketahui dalam pipeline:

  • x-aggrega-selector: — dihasilkan oleh sintesis usesSchema: dan featuresSchema: untuk membawa string selector yang menargetkan Components penyedia yang kompatibel.
  • x-aggrega-sensitive: — dihasilkan oleh leaf yang mendeklarasikan sensitive: true. Lihat Mendeklarasikan leaf sebagai sensitif di atas.

Penulis katalog yang menulis kata kunci ekstensi mereka sendiri menggunakan namespace yang sama; tooling hilir yang mengonsumsi JSON Schema hasil kompilasi membaca kunci x-aggrega-* tanpa bertabrakan dengan ruang kata kunci milik JSON Schema sendiri.

Contoh lengkap — skema Component MariaDB

Sebuah skema Component representatif dalam bentuk ringkas untuk datastore MariaDB, yang menunjukkan bentuk tersirat di seluruh bagian, batasan leaf campuran, referensi, bentuk bersyarat, dan contoh oneOf untuk blok autentikasi:

spec:
schema:
values:
architecture:
type: string
enum: [standalone, replication]
default: standalone
description: |
Topology mode. `standalone` runs a single primary; `replication` runs a primary
plus N secondary replicas governed by the secondary block.
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary:
when: '{{ eq $.architecture "replication" }}'
properties:
replicaCount: { type: integer, min: 2, max: 8, default: 2 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, sensitive: true, required: true }
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics:
enabled: { type: boolean, default: false }
serviceMonitor:
enabled: { type: boolean, default: false }
namespace: { type: string }
labels: { type: object, valuesType: string }
$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec:
size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true }
storageClass: { type: string }

Jika ditulis sebagai YAML JSON Schema, kontrak yang sama harus menuliskan type: object, properties:, dan additionalProperties: false untuk setiap objek, serta mencantumkan ulang setiap field wajib di required: milik induknya, sehingga jauh lebih panjang. Keuntungan keringkasan ini berlipat pada kontrak Component yang lebih besar dan cukup berarti untuk menjadikan bentuk ringkas sebagai permukaan penulisan bawaan untuk schema:, parameters:, dan entri SchemaLibrary.

Rujukan silang

  • Untuk semantik resolusi $ref: lintas dokumen (sintaks required: di samping referensi lintas dokumen; ekspansi rantai dari pustaka ke pustaka; konsumen mempersempit pustaka): cross-document-ref.md.
  • Untuk tata bahasa penulisan blok assertions: (aturan lintas bidang yang tidak dapat diekspresikan oleh validate: bentuk ringkas): templates/assertions-block.md.
  • Untuk himpunan pilar data yang menampung skema bentuk ringkas (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Untuk aturan ekspansi singkatan URI OCI (domain default, segmen registri, fallback versi, ekspansi penerbit): uri-grammar.md.
  • Untuk penulisan entitas SchemaLibrary (tempat skema yang dapat dirujuk dengan $ref: berada di katalog): ../entities/schemalibrary.md.