Lược đồ Aggrega Developer Intent (Aggregate)
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id lược đồ: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
Kiến trúc AI đệ quy, có tham số hóa. Đóng vai trò vừa là gốc của một bản build vừa là mô-đun có thể tái sử dụng.
Xem tài liệu tham khảo về cách soạn Aggregate để có hướng dẫn chi tiết về cách soạn các thực thể Aggregate; trang này mô tả lược đồ cấu trúc mà tài liệu tham khảo đó trình bày.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | có | Hằng số: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | có | Hằng số: "Aggregate" |
metadata | object | có | |
defs | string[] | không | Khối tùy chọn dành cho các YAML anchor tiêu chuẩn (& và *) để giữ Aggregate theo nguyên tắc DRY, đồng thời duy trì một từ điển phẳng O(1) cho trình biên dịch. Tương ứng với khối tương đương trên Manifest. |
spec | object | có | Bề mặt Developer Intent: hợp đồng tham số toàn cục, các import aggregate lồng nhau, API công khai gồm các component được xuất, các nhóm subsystem, và các instance component tạo nên module. |
Không cho phép thuộc tính bổ sung.
aggregate.metadata
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Dài ít nhất 1 ký tự. |
version | string | có | Phiên bản theo Semantic Versioning nghiêm ngặt của mô-đun aggregate. Mẫu: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | không | |
maintainers | object[] | không | Danh sách những người bảo trì sở hữu thực thể này. |
license | string | không | Mã định danh SPDX cho giấy phép của phần mềm mà thực thể này mô tả, chẳng hạn MIT hoặc AGPL-3.0. Nó ghi lại các điều khoản của phần mềm đó, không phải các điều khoản của tệp này. |
repository | string | không | URL đến kho Git chứa các tệp nguồn. |
home | string | không | URL của trang chủ, wiki hoặc tài liệu của thực thể này. |
keywords | string[] | không | Danh sách các từ khóa mô tả giúp dễ tìm kiếm trên giao diện người dùng. |
labels | map của string | không | Các nhãn duck-typing cấp module dùng cho việc khám phá catalog, đánh giá chính sách và lọc trong Studio/IDE. Các nhãn này mô tả danh tính của Aggregate như một module tái sử dụng được (ví dụ: aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). Chúng KHÔNG lan truyền xuống các nút component con — nhãn của component chỉ đến từ thực thể catalog Component trong Domain 2. |
Không cho phép thuộc tính bổ sung.
aggregate.metadata.maintainers[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | |
email | string | không | |
url | string | không |
Không cho phép thuộc tính bổ sung.
aggregate.spec
Bề mặt Developer Intent: hợp đồng tham số toàn cục, các import aggregate lồng nhau, API công khai gồm các component được xuất, các nhóm subsystem, và các instance component tạo nên module.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
parameters | map của object | không | Hợp đồng môi trường toàn cục. Mỗi mục là một đối tượng hợp đồng có kiểu, sử dụng tập con từ vựng dạng rút gọn (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). Cấu trúc lồng nhau được biểu diễn qua trường con properties: của dạng có kiểu. Việc đáp ứng trong Release có thể là nội tuyến (parameters: {…}) hoặc import từ một tệp nguồn duy nhất (parameters: {$import: |
aggregates | map của object | không | Các aggregate lồng nhau đóng vai trò module được import. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
exportedComponents | map của string | không | Giao diện API công khai. Ánh xạ một tên công khai được phơi bày tới một ID component nội bộ. Các Aggregates cha import module này tham chiếu đến các component bằng các tên công khai này. |
subsystems | map của subsystem | không | Các nhóm logic có tên, gom các component của một Aggregate thành các subsystem. Loại trừ lẫn nhau với components cấp cao nhất — khai báo cả hai sẽ bị từ chối. Một subsystem do tác giả đặt tên default là một subsystem được khai báo thông thường, khác với default được tổng hợp mà trình biên dịch tạo ra cho một Aggregate chỉ có components. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
components | map của component_instance | không | Map các component nguyên tử logic tạo nên Aggregate này, được viết trực tiếp ở cấp cao nhất. Components cấp cao nhất và subsystems loại trừ lẫn nhau — khai báo cả hai sẽ bị từ chối. Khi components được viết ở đây (không có subsystems), trình biên dịch gộp chúng vào một subsystem default được tổng hợp khi tải, và IR đánh dấu subsystem đó là được tổng hợp. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.
Định nghĩa
inject_delivery
Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa tùy chỉnh riêng cho cơ chế) cùng với đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’ (một chuỗi literal, có thể chứa các biểu thức Go template được đánh giá khi phân giải self-inject). ‘from’ phân giải theo provides của đích trong ngữ cảnh uses[].inject, theo provides mà FeatureRecipe của attachment công bố trong ngữ cảnh features.
Loại: object[]
inject_block
Định tuyến injection không phụ thuộc vào nội dung. Ánh xạ các biến cục bộ tới các khóa provides của đích (uses[].inject), tới các khóa provides mà FeatureRecipe của một attachment công bố (features.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
env | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa tùy chỉnh riêng cho cơ chế) cùng với đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’ (một chuỗi literal, có thể chứa các biểu thức Go template được đánh giá khi phân giải self-inject). ‘from’ phân giải theo provides của đích trong ngữ cảnh uses[].inject, theo provides mà FeatureRecipe của attachment công bố trong ngữ cảnh features. |
file | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa tùy chỉnh riêng cho cơ chế) cùng với đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’ (một chuỗi literal, có thể chứa các biểu thức Go template được đánh giá khi phân giải self-inject). ‘from’ phân giải theo provides của đích trong ngữ cảnh uses[].inject, theo provides mà FeatureRecipe của attachment công bố trong ngữ cảnh features. |
arg | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa tùy chỉnh riêng cho cơ chế) cùng với đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’ (một chuỗi literal, có thể chứa các biểu thức Go template được đánh giá khi phân giải self-inject). ‘from’ phân giải theo provides của đích trong ngữ cảnh uses[].inject, theo provides mà FeatureRecipe của attachment công bố trong ngữ cảnh features. |
component_uses_block
Các kết nối mà một component vẽ tới các component mà nó phụ thuộc, được đánh khóa theo socket. Mỗi socket liệt kê các đích của nó, hoặc đặt tên cho từng kết nối dưới một bí danh. Một kết nối được đặt tên dưới bí danh có thể mang các giá trị theo từng kết nối của nhà phát triển và các attachment lấp đầy các slot mà socket khai báo.
Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$.
Giá trị là string[] or map of object.
Không cho phép bất kỳ khóa nào khác.
feature_uses_block
Các kết nối mà một Feature được gắn vẽ ra, được đánh khóa theo một socket mà Feature khai báo trong usesSchema của nó. Mỗi socket liệt kê các đích của nó, hoặc đặt tên cho từng kết nối dưới một bí danh. Một kết nối mà Feature vẽ ra không mang attachment riêng: một thông tin xác thực mà nó cần sẽ lấp đầy một slot mà Feature khai báo trong featuresSchema của chính nó và được gắn bên cạnh Feature.
Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$.
Giá trị là string[] or map of object.
Không cho phép bất kỳ khóa nào khác.
connection_attachment
Một attachment mà một kết nối mang theo: Feature lấp đầy một slot mà socket của kết nối khai báo, cùng với cấu hình của nhà phát triển dành cho nó.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
type | string | có | URI của giao diện Feature mà attachment này yêu cầu (ví dụ core/referenced-secret:1.0.0). |
description | string | không | Tài liệu tùy chọn giải thích vì sao kết nối này mang attachment. |
values | object | không | Cấu hình do nhà phát triển cung cấp cho Feature, được xác thực theo khai báo schema của nó. |
Không cho phép thuộc tính bổ sung.
subsystem
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
description | string | không | Tài liệu tùy chọn mô tả mục đích của subsystem này và nhóm logic mà nó đại diện. |
annotations | map của string hoặc object hoặc null | không | Các annotation do nhà phát triển viết trên subsystem này. Giá trị là chuỗi, đối tượng có cấu trúc (một map từ khóa con tới giá trị, được hợp nhất theo từng khóa con với một giá trị có cấu trúc được kế thừa), hoặc null; null tường minh trên một khóa được kế thừa từ subsystem cha sẽ gỡ binding được kế thừa khỏi subsystem này (opt-out Feature dựa trên annotation). Các annotation khai báo ở đây được kế thừa bởi các subsystem lồng nhau và các component chứa trong đó; cấp gần hơn thắng theo từng khóa. Lan xuống bucket .context.annotations.aggregate trên mỗi nút IR được dẫn xuất. |
features | map của object | không | Các feature xuyên suốt được gắn vào tất cả component trong subsystem này. Cùng schema với feature cấp component (type, values, uses, inject). Được làm phẳng vào từng component khi hoàn tất đồ thị, đặt sau các feature cấp component trong thứ tự thực thi. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
subsystems | map của subsystem | không | Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
components | map của component_instance | không | Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.
component_instance
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
type | string | có | Component trừu tượng được yêu cầu, ở dạng tham chiếu: metadata.name của nó cộng với một :version tùy chọn (ví dụ core/api-server:1.0.0), không bao giờ là đường dẫn tệp. Được phân giải qua Mô hình phân giải thực thể ba tầng (các thư mục catalog của workspace → cache → registry): một Component được soạn cục bộ được đặt trong catalog/ ở gốc workspace hoặc trong một thư mục được liệt kê trong workspace.catalog_dirs, và một type được viết dưới dạng đường dẫn tệp tương đối sẽ dừng bản build như một thực thể không catalog nào chứa. |
active | boolean hoặc string | không | Component này có hiện diện trong topology đã biên dịch hay không. Một giá trị boolean, hoặc một string template trên .parameters phải phân giải thành boolean. Khi giá trị phân giải thành false, component bị loại khỏi topology, kéo theo các cạnh uses và các attachment của nó. Việc lấy giá trị từ một parameter cho phép một Release bật/tắt sự hiện diện của component bằng cách cung cấp parameter đó. Mặc định là true khi bị bỏ qua. Mặc định: true |
description | string | không | Tài liệu tùy chọn mô tả vai trò của component instance này trong ứng dụng. Được mang theo vào đồ thị IR. |
annotations | map của string hoặc object hoặc null | không | Các chú thích do nhà phát triển viết trên component này. Giá trị là chuỗi, đối tượng có cấu trúc (một map từ khóa con tới giá trị, được hợp nhất theo từng khóa con với một giá trị có cấu trúc được kế thừa), hoặc null; null tường minh trên một khóa được kế thừa từ subsystem cha sẽ gỡ bỏ liên kết được kế thừa khỏi component này (cơ chế từ chối Feature dựa trên chú thích). Các chú thích cấp Component ghi đè các chú thích cấp subsystem được kế thừa theo từng khóa; các component anh em trong cùng một subsystem giữ các bảng chú thích riêng của chúng một cách độc lập. |
values | object | không | Các thuộc tính nhận thức không trong suốt được truyền cho Component, được xác thực bởi schema của nó. |
uses | component_uses_block | không | Các kết nối mà một component vẽ tới các component mà nó phụ thuộc, được đánh khóa theo socket. Mỗi socket liệt kê các đích của nó, hoặc đặt tên cho từng kết nối dưới một bí danh. Một kết nối được đặt tên dưới bí danh có thể mang các giá trị theo từng kết nối của nhà phát triển và các attachment lấp đầy các slot mà socket khai báo. |
inject | inject_block | không | Self-inject cấp component. Inject các giá trị riêng của component (qua ‘value:’) hoặc các khóa provides riêng của nó (qua ‘from:’) trực tiếp vào đường ống phân phối (.context.inject). Chỉ được phép nếu thực thể catalog Component khai báo ‘spec.inject’ với các cơ chế tương ứng. Một khóa inject trùng với một khóa được khai báo trong uses[].inject sẽ dừng bản build như một khóa phân phối trùng lặp giữa các nguồn inject. |
features | map của object | không | Các Features được gắn vào component này, được đánh khóa theo tên instance mà tác giả đặt cho mỗi attachment. Đây là bề mặt gắn duy nhất: một Feature vận hành, một Feature thông tin xác thực (Feature được gắn nhãn feature.aggrega.ai/kind: secret) và một Feature định danh đều được gắn ở đây, dưới cùng một từ khóa và cùng một cấu trúc. Điểm khác nhau giữa chúng là những gì attachment tạo ra, không phải cách nó được khai báo. Một attachment có tên instance khớp với một slot mà Component khai báo trong featuresSchema sẽ lấp đầy slot đó; mọi tên instance khác là một attachment tự do. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.