Skema Aggrega Entity Lock
Referensi yang dihasilkan. Jangan diedit secara manual — hasilkan ulang dari JSON Schema yang dipublikasikan.
Id skema: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json
Berkas entity.lock yang terletak di samping sebuah entitas dan mencatat pin konten untuk masukan yang dijangkau entitas tersebut di luar dokumennya sendiri: berkas yang diimpor oleh artefaknya, berkas dari sumber lokal, dan sumber jarak jauh yang identitasnya ditulis lengkap oleh entitas — serta, untuk sumber lokal berupa direktori, aturan yang menentukan berkas mana saja yang termasuk dalam entitas. Satu langkah menulisnya: aggrega pin, yang dijalankan oleh penulis entitas dan tidak memerlukan Release. aggrega pull dan aggrega push menjalankan langkah yang sama, dan menulis byte yang sama, bila diminta — dengan --pin-sources, atau dengan pin_sources_at_pull atau pin_sources_at_push milik workspace. Pull yang tidak diminta melakukan pin tidak menulis apa pun di sini: atas entitas di direktori katalog workspace sendiri, pull membandingkan apa yang akan dicatat oleh langkah tersebut dengan isi berkas, lalu berhenti, dengan menyebut aggrega pin, bila sebuah pin hilang atau tidak lagi cocok dengan masukannya — untuk sumber lokal, berkas yang ditambahkan, diubah, atau dihapus sejak pin menghentikan pull seperti pin usang lainnya. aggrega build membacanya kembali dan berhenti bila isi di disk tidak lagi menghasilkan digest yang tercatat. Cakupannya ditentukan oleh direktori tempatnya berada — berkas ini mem-pin masukan entitas di direktori tersebut — sehingga satu nama berkas melayani setiap jenis alih-alih setiap jenis memiliki ejaannya sendiri. Langkah tersebut menghapus lock dari entitas yang tidak membaca masukan semacam itu, alih-alih meninggalkan lock kosong. Dokumen entitas itu sendiri tidak pernah ditulis oleh mesin: apa yang diketik penulis tetap persis seperti yang diketik, dan apa yang diturunkan mesin disimpan di sini. Pemisahan inilah yang membuat lock aman untuk di-commit dan mudah dibaca sebagai diff, karena setiap baris menyebut satu masukan dan digest yang berubah menunjukkan masukan yang berubah. Berkas ini tidak memuat stempel waktu maupun metadata resolusi, sehingga menjalankan ulang langkah tersebut atas masukan yang tidak berubah membuat berkas identik byte demi byte. Satu bentuk baris melayani setiap jenis yang dapat mencatat pin, sehingga sebuah pin terbaca identik apa pun jenis pemiliknya. Bentuk wire bersifat tertutup (additionalProperties: false). Disiplin evolusi skema: menambahkan field opsional baru adalah SemVer-MINOR (aditif); menghapus field atau memperketat batasan adalah SemVer-MAJOR.
Jenis tingkat teratas: object
Properti
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
version | const 1 | ya | Versi skema entity-lock: 1. Perubahan SemVer-MAJOR pada skema menaikkannya. Konstanta: 1 |
sourceDigests | object[] | tidak | Pin konten untuk sumber jarak jauh yang dirujuk entitas ini dan identitasnya ditulis lengkap oleh entitas, dibekukan saat resolusi dari byte yang diambil dan dibaca kembali saat build untuk memverifikasi bahwa sumber dalam cache tidak bergeser. Setiap entri mencerminkan identitas sumber yang telah diresolusi {kind, url, chart, moduleSubdir, version} ditambah digest konten (dan, untuk sumber yang didistribusikan melalui OCI, digest manifest). Sumber yang identitasnya diisi dari templat — misalnya versi yang dibaca dari nilai infrastruktur sebuah Release — tidak memiliki entri di sini: artefak mana yang dinamainya ditentukan oleh setiap Release yang menggunakan entitas tersebut, sehingga setiap identitas hasil resolusinya di-pin dalam lockfile Release tersebut. Sumber lokal (relatif terhadap sistem berkas) juga tidak memiliki entri di sini: sumber itu menamai sebuah path, bukan sesuatu yang diambil, sehingga tidak ada arsip yang diperoleh untuk di-pin, dan berkas-berkasnya di-pin satu per satu dalam localSourceDigests. |
artifactDigests | object[] | tidak | Pin konten untuk berkas yang diimpor oleh artefak entitas ini melalui $import — untuk sebuah Recipe, termasuk yang diimpor oleh entri boundary.artifacts-nya — dibekukan saat resolusi dan dibaca kembali saat build untuk memverifikasi bahwa berkas yang diimpor tidak bergeser. Satu entri per artefak yang nilainya berupa impor berkas; artefak inline (literal) sudah menjadi bagian dari entitas dan tidak memiliki pin tersendiri, dan artefak yang diambil dari pustaka di-pin oleh versi hasil resolusi pustaka tersebut. Build membandingkan entri dari kedua blok dengan pinnya dengan cara yang sama, dan menolak berkas yang tidak lagi cocok dengannya dalam kondisi yang sama. |
localSourceDigests | object[] | tidak | Pin konten untuk berkas-berkas sumber lokal entitas ini — sumber yang ditulis sebagai path di samping entitas, bukan diambil — dibekukan saat entitas di-pin dan dibaca kembali saat build untuk memverifikasi bahwa berkas-berkas tersebut tidak bergeser. Satu entri per berkas yang dikontribusikan sumber ke isi publikasi entitas: setiap berkas di bawah direktori yang dinamai sumber yang dipertahankan oleh aturan yang tercatat di ignore, atau satu berkas yang dinamainya. Sumber lokal yang ditulis sebagai templat baru menamai direktorinya setelah sebuah Release mengisi templat tersebut, sehingga sumber itu mengontribusikan setiap berkas di direktori entitas itu sendiri yang dipertahankan oleh aturan yang tercatat, dan masing-masing berkas tersebut di-pin. Dokumen entitas, .aggregaignore milik penulis di sampingnya, dan berkas ini tidak pernah menjadi entri: dokumen adalah entitas itu sendiri, aturan berkas ignore dicatat di ignore, dan lock tidak dapat mencatat digest-nya sendiri. Setelah lock mencatat entri apa pun di sini, build menolak sumber yang memuat berkas tanpa entri, berkas yang kontennya tidak lagi menghasilkan digest sesuai entrinya, atau yang tidak memiliki berkas yang dinamai sebuah entri. |
ignore | object | tidak | Aturan yang menentukan berkas mana di bawah direktori sumber lokal entitas ini yang menjadi miliknya, dicatat saat entitas di-pin. Setiap pembacaan direktori tersebut selanjutnya menerapkan aturan ini dan tidak ada yang lain: publikasi entitas, perbandingan yang dilakukan pull atau publikasi terhadap lock, baris entitas milik penulis, perbandingan build beserta render-nya, dan pull yang memverifikasi. Jadi, perubahan pada .aggregaignore milik penulis, pada binding provider di workspace, atau pada biner aggrega tidak menggeser digest apa pun sampai entitas di-pin kembali, dan mem-pin-nya kembali menampilkan perubahan tersebut di sini sebagai diff. Hanya ada jika entitas mendeklarasikan sumber lokal yang berupa direktori, atau yang ditulis sebagai templat. Lock yang tidak mencatat aturan apa pun mempertahankan setiap berkas di bawah direktori tersebut. Tautan simbolis di mana pun di bawahnya ditolak, bukan diikuti. |
Properti tambahan tidak diizinkan.
entity-lock.sourceDigests[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
kind | enum | ya | Jenis sumber yang telah diresolusi. Salah satu dari himpunan tertutup — himpunan yang sama dengan yang dibawa oleh kind source-artifact pada lockfile dan kind pada metadata cache — karena ketiganya mencatat identitas sumber hasil resolusi yang sama dan build membaca jenis tersebut untuk memilih loader. terraform-module-oci termasuk dalam himpunan tersebut, dan tidak ada adaptor sumber yang melayaninya: Recipe atau FeatureRecipe yang menyebutkannya ditolak saat dibaca. Nilai yang diizinkan: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | ya | URL sumber yang ditulis penulis dan di-pin oleh digest — URL identitas sebagaimana ditulis di spec.source.url (root repo atau .tgz langsung untuk helm-https-chart). Build merekonstruksi URL yang sama ini secara offline, sehingga URL ini adalah identitas stabil yang menjadi kunci pin, bukan lokasi artefak hasil resolusi. |
chart | string | tidak | Nama chart untuk sumber helm berbasis root repo (spec.source.chart), bagian dari identitas sumber hasil resolusi sehingga dua chart yang disajikan dari satu root repo pada versi yang sama di-pin secara terpisah. Tidak ada untuk sumber .tgz langsung, OCI, compose, atau git, yang tidak satu pun memilih chart di dalam URL. |
moduleSubdir | string | tidak | Direktori di dalam repositori bersumber git yang merupakan artefak (spec.source.module_subdir), bagian dari identitas sumber hasil resolusi sehingga dua direktori dari satu repositori pada commit yang sama di-pin secara terpisah. Tidak ada jika seluruh repositori adalah artefaknya, dan untuk setiap jenis yang menjangkau artefaknya melalui URL alih-alih dengan menelusuri ke dalam clone. |
version | string | ya | Versi konkret yang di-pin hasil resolusi sumber — versi chart untuk jenis helm-*, commit hasil resolusi referensi git-repository. Dicatat sebagai satu segmen path, karena versi ini membentuk slot cache tempat build membaca kembali sumber, sehingga tidak memuat /, \, maupun ... Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | ya | Digest konten arsip sumber yang diambil, dalam format sha256: diikuti 64 karakter heksadesimal huruf kecil, diverifikasi terhadap byte dalam cache saat build. Pola: ^sha256:[a-f0-9]{64}$. |
manifestDigest | string | tidak | Digest manifest OCI untuk sumber yang didistribusikan melalui OCI — akar kepercayaan yang independen — dalam format sha256: diikuti 64 karakter heksadesimal huruf kecil. Hanya ada untuk sumber OCI (helm-oci-chart); tidak ada untuk sumber https atau git, yang secara konstruksi tidak memiliki manifest. Pola: ^sha256:[a-f0-9]{64}$. |
Properti tambahan tidak diizinkan.
entity-lock.artifactDigests[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | Berkas $import milik artefak mana yang di-pin oleh entri ini: kunci map artifacts: untuk entri artifacts, dan boundary/ diikuti kunci untuk entri boundary.artifacts sebuah Recipe — sehingga entri dari masing-masing blok yang ditulis dengan satu kunci yang sama di-pin secara terpisah. |
digest | string | ya | Digest konten byte berkas yang diimpor, dalam format sha256: diikuti 64 karakter heksadesimal huruf kecil, diverifikasi saat build. Pola: ^sha256:[a-f0-9]{64}$. |
Properti tambahan tidak diizinkan.
entity-lock.localSourceDigests[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
path | string | ya | Path berkas relatif terhadap direktori yang memuat dokumen entitas, ditulis dengan garis miring maju — misalnya charts/app/templates/deployment.yaml. |
digest | string | ya | Digest konten byte berkas, dalam format sha256: diikuti 64 karakter heksadesimal huruf kecil, diverifikasi saat build. Pola: ^sha256:[a-f0-9]{64}$. |
Properti tambahan tidak diizinkan.
entity-lock.ignore
Aturan yang menentukan berkas mana di bawah direktori sumber lokal entitas ini yang menjadi miliknya, dicatat saat entitas di-pin. Setiap pembacaan direktori tersebut selanjutnya menerapkan aturan ini dan tidak ada yang lain: publikasi entitas, perbandingan yang dilakukan pull atau publikasi terhadap lock, baris entitas milik penulis, perbandingan build beserta render-nya, dan pull yang memverifikasi. Jadi, perubahan pada .aggregaignore milik penulis, pada binding provider di workspace, atau pada biner aggrega tidak menggeser digest apa pun sampai entitas di-pin kembali, dan mem-pin-nya kembali menampilkan perubahan tersebut di sini sebagai diff. Hanya ada jika entitas mendeklarasikan sumber lokal yang berupa direktori, atau yang ditulis sebagai templat. Lock yang tidak mencatat aturan apa pun mempertahankan setiap berkas di bawah direktori tersebut. Tautan simbolis di mana pun di bawahnya ditolak, bukan diikuti.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
plugin | object | tidak | Plugin yang melayani kapabilitas entitas di workspace penulis saat entitas di-pin — binding provider workspace untuk kapabilitas tersebut, atau jika tidak ada, plugin yang terpasang di dalam biner aggrega — yang disebutkan tanpa versi, beserta aturan ignore yang dideklarasikannya. Tidak ada versi maupun digest plugin yang dicatat: aturanlah yang diterapkan setiap pembacaan, sehingga melakukan pin ulang di bawah rilis lain dari plugin yang sama membiarkan lock tidak berubah kecuali aturannya berubah. Pull yang plugin-nya sendiri untuk kapabilitas tersebut mendeklarasikan aturan berbeda menyampaikannya dalam sebuah peringatan (advisory), dengan menyebutkan kedua plugin dan perbedaannya, dan tidak pernah berhenti karenanya. Tidak ada jika tidak ada plugin yang melayani kapabilitas tersebut. |
rules | object[] | tidak | Aturan tersusun yang persis, dalam urutan penerapannya: pola milik plugin, lalu baris-baris setiap file ignore yang disebutkan plugin dan ditemukan oleh penelusuran, dengan file milik suatu direktori sebelum file di bawahnya, lalu baris-baris .aggregaignore milik penulis di samping entitas. Kecocokan yang lebih akhir menimpa yang lebih awal, sehingga file milik penulis menjadi penentu terakhir untuk setiap path yang disebutkannya, dan baris yang diawali dengan ! mengembalikan apa yang dikecualikan oleh aturan sebelumnya. Direktori yang dikecualikan oleh suatu aturan tidak dimasuki, sehingga file di bawahnya baru kembali setelah direktori tersebut kembali. |
Properti tambahan tidak diizinkan.
entity-lock.ignore.plugin
Plugin yang melayani kapabilitas entitas di workspace penulis saat entitas di-pin — binding provider workspace untuk kapabilitas tersebut, atau jika tidak ada, plugin yang terpasang di dalam biner aggrega — yang disebutkan tanpa versi, beserta aturan ignore yang dideklarasikannya. Tidak ada versi maupun digest plugin yang dicatat: aturanlah yang diterapkan setiap pembacaan, sehingga melakukan pin ulang di bawah rilis lain dari plugin yang sama membiarkan lock tidak berubah kecuali aturannya berubah. Pull yang plugin-nya sendiri untuk kapabilitas tersebut mendeklarasikan aturan berbeda menyampaikannya dalam sebuah peringatan (advisory), dengan menyebutkan kedua plugin dan perbedaannya, dan tidak pernah berhenti karenanya. Tidak ada jika tidak ada plugin yang melayani kapabilitas tersebut.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
name | string | ya | Plugin yang melayani kapabilitas entitas saat entitas di-pin, sebagai <pluginType>/<name>, tanpa versi: aturan di bawah inilah yang diterapkan pembacaan, dan namanya menyatakan milik siapa aturan tersebut. Panjang minimal 1 karakter. |
patterns | string[] | tidak | Pola ignore yang dideklarasikan plugin, sebagaimana plugin mendeklarasikannya. |
files | string[] | tidak | Nama-nama file ignore yang menurut deklarasi plugin dipatuhi oleh ekosistemnya di dalam suatu sumber. |
Properti tambahan tidak diizinkan.
entity-lock.ignore.rules[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
pattern | string | ya | Satu pola ignore dalam sintaks gitignore. |
within | string | ya | Direktori yang menjadi cakupan pola, relatif terhadap direktori yang memuat dokumen entitas dan ditulis dengan garis miring maju; . menyebut direktori itu sendiri. Pola yang dideklarasikan plugin dicakupkan ke direktori sumber lokal, baris dari file ignore ke direktori yang memuat file tersebut, dan baris dari .aggregaignore milik penulis ke direktori entitas. |
from | string | ya | Tempat pola dideklarasikan: plugin untuk pola yang dideklarasikan plugin, dan selain itu path file ignore tempat pola dibaca, relatif terhadap direktori yang memuat dokumen entitas. |
Properti tambahan tidak diizinkan.