SchemaLibrary
Một SchemaLibrary là một thực thể catalog chứa các định nghĩa JSON Schema 2020-12 có thể tái sử dụng cùng với các helper có tham số tùy chọn. Các Components và Features dùng chung các dạng schema — URL, khoảng thời gian, cấu trúc probe phổ biến, giới hạn tài nguyên lặp lại — khai báo các dạng đó một lần trong một thư viện và tham chiếu chúng qua các URI $ref chuẩn. Thực thể thư viện thuộc Tier 3: tùy chọn dành cho các catalog cần tái sử dụng schema giữa các Component. Các catalog không có nội dung schema lặp lại được phát hành mà không có SchemaLibrary nào.
Vai trò của SchemaLibrary
Các kiến trúc sư nền tảng tạo các SchemaLibraries để tập trung các cấu trúc schema lặp lại trong toàn bộ catalog. Một library không phải là một khối xây dựng có thể triển khai; nó là một không gian tên chứa các định nghĩa. Tác giả Component / Feature tham chiếu các mục của library bằng URI $ref chuẩn của chúng, được định kiểu một lần và được kiểm tra hợp lệ ở mọi nơi tham chiếu được phân giải.
Việc phân tách giữa “library” và “bên sử dụng” là có chủ đích. Components khai báo hợp đồng mà một instance điền vào (values, infra và provides của nó, các socket của nó, các slot thông tin xác thực của nó). Features mã hóa các phần gắn kèm về hành vi. SchemaLibraries chỉ mã hóa nội dung schema — các quy tắc cấu trúc mà một giá trị phải thỏa mãn. Giữ ba vai trò này tách biệt cho phép mỗi loại thực thể phát triển theo nhịp độ riêng; những tác giả không cần các định nghĩa schema dùng chung sẽ không bao giờ gặp thực thể library.
Lớp vỏ thực thể
Một thực thể SchemaLibrary mang lớp vỏ catalog tiêu chuẩn. apiVersion: aggrega.ai/v1beta1 và kind: SchemaLibrary đánh dấu loại thực thể; metadata.name là một định danh dạng PascalCase; metadata.version tuân theo phiên bản ngữ nghĩa (semantic versioning) nghiêm ngặt. Nội dung của thư viện nằm dưới spec: spec.schemas là bắt buộc (thư viện phải khai báo ít nhất một mục), còn spec.templates là tùy chọn (chỉ có mặt khi thư viện dùng các hàm trợ giúp có tham số).
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Soạn các mục schema
Các mục schema được soạn theo một trong ba dạng. Dạng rút gọn là bề mặt mặc định cho các hình dạng ngắn, phổ biến — type, pattern, enum, min, max và các ràng buộc một dòng tương tự. YAML JSON Schema 2020-12 là lựa chọn soạn thảo ngang hàng cho các mục cần toàn bộ bề mặt JSON Schema (các từ khóa kết hợp, hình dạng có điều kiện, $defs phức tạp). Việc trộn hai dạng trong cùng một mục được hỗ trợ thông qua cơ chế phân phối theo hình dạng nội dung ở từng nút của trình biên dịch dạng rút gọn; lối thoát $jsonschema: nhúng nội dung JSON Schema đầy đủ tại bất kỳ nút nào khi dạng rút gọn không thể diễn đạt ý định.
Một format trong một mục kiểm tra đúng những gì nó kiểm tra trong bất kỳ schema nào: nó nêu tên một trong email, uri, hostname, ipv4, ipv6, uuid, date-time và date, và một giá trị mà bên sử dụng cung cấp cho trường sẽ bị từ chối trừ khi nó có định dạng đó — xem vocabulary/compact-form-authoring.md. Một mục nêu tên bất kỳ định dạng nào khác — kể cả password — sẽ bị từ chối khi thư viện được nạp, vì vậy lệnh aggrega validate trên toàn bộ catalog sẽ từ chối nó dù hiện đã có gì tham chiếu đến nó hay chưa, nêu tên thư viện, mục và tên định dạng, đồng thời liệt kê các định dạng được hỗ trợ; và một lần build hoặc pull có Release chạm tới thư viện sẽ dừng lại vì nó. Một mục tham chiếu đến thư viện khác được đánh giá tại nơi một trụ cột Component hoặc Feature sử dụng nó. Một trường mang dữ liệu bí mật khai báo sensitive: true thay vì một định dạng.
Template và $instantiate:
Các thư viện có cấu trúc lặp lại đáng kể khai báo các helper có tham số dưới spec.templates. Một template mang một map $params: (các khai báo tham số có tên và có kiểu) cùng với một phần thân (dạng compact hoặc nội dung JSON Schema tham chiếu các tham số dưới dạng token vô hướng $<paramName>). Các mục schema khởi tạo template thông qua các ràng buộc $instantiate: + $args:; bộ máy thay thế sẽ thay các placeholder tham số bằng các giá trị vô hướng literal và tạo ra phần thân của mục đã được phân giải.
spec: schemas: LivenessProbe: $instantiate: ProbeTemplate $args: port: 8080 path: /healthz ReadinessProbe: $instantiate: ProbeTemplate $args: port: 8081 path: /ready templates: ProbeTemplate: $params: port: type: integer path: type: string type: object properties: port: type: integer const: $port path: type: string const: $pathViệc thay thế chỉ áp dụng cho giá trị vô hướng literal. Bộ máy thay thế không diễn giải cú pháp template của Go, không đánh giá điều kiện và không chạy vòng lặp. Những tác giả cần các helper có khả năng biểu đạt cao hơn sẽ kết hợp các Components hoặc Features tiêu thụ các mục của thư viện với các biến thể riêng của họ.
Quy ước đặt tên
Tên thư viện, khóa của các mục schema và tên template tuân theo PascalCase. JSON Schema của phong bì thực thể thực thi quy ước này tại ba vị trí thông qua các ràng buộc mẫu:
metadata.namekhớp với^[A-Z][A-Za-z0-9]*$.- Các khóa của map
spec.schemaskhớp với cùng mẫu đó thông quapropertyNames. - Các khóa của map
spec.templateskhớp với cùng mẫu đó thông quapropertyNames.
Một SchemaLibrary có khóa không theo PascalCase trong spec.schemas hoặc spec.templates sẽ không vượt qua bước xác thực phong bì khi tải workspace. Việc thực thi ở cấp phong bì đóng vai trò then chốt: khóa của các mục schema xuất hiện trong các URI $id chuẩn tắc (#/schemas/<name>); tên template tham chiếu vào các URI chuẩn tắc tại thời điểm khởi tạo. Việc phát hiện các khóa không theo PascalCase ngay khi tải ngăn chúng lan truyền qua hệ sinh thái catalog.
Tên tham số bên trong map $params: của một template là cục bộ đối với template — chúng không xuất hiện trong các URI $id chuẩn tắc và không bị ràng buộc mẫu ở cấp phong bì. Tác giả tuân theo bất kỳ quy ước đặt tên nào phù hợp với các tham số của template; port, path, intervalSec và các tên tham số viết thường tương tự là điển hình.
Sự đồng nhất trong cách đặt tên ở các cấp thư viện, schema và template giúp các định danh tham chiếu dễ đọc: WebPrimitives#/schemas/URL có thể hiểu ngay khi nhìn qua.
Về ngữ nghĩa phân giải $ref: xuyên tài liệu — cách $ref: được phân giải qua ranh giới giữa các SchemaLibrary, sự khác biệt về cú pháp required: đối với các bên tiêu thụ có mang $ref:, việc mở rộng chuỗi từ thư viện sang thư viện, và hành vi bên tiêu thụ thu hẹp thư viện — xem vocabulary/cross-document-ref.md.
Tham chiếu các mục của thư viện
Tác giả Component / Feature tham chiếu một mục của thư viện bằng định danh của nó — dạng tên trần <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"Tên thư viện được phân giải dựa trên catalog đã phân giải; fragment #/schemas/<name> chọn mục. Một tham chiếu không mang registry host; tác giả có thể khẳng định một ngưỡng phiên bản tối thiểu tùy chọn dưới dạng <Library>:<version>#/schemas/<name> (dấu phân cách phiên bản là :, khớp với các mapping của recipe/feature và pin trong lockfile), nhưng phiên bản được phân giải do lockfile của từng Release cung cấp, lockfile này pin mỗi thư viện được sử dụng theo tên + phiên bản + digest nội dung. Một tham chiếu mang registry host — dạng oci://<host>/… — bị từ chối khi biên dịch với một chẩn đoán hướng tác giả sang dạng định danh, nhờ vậy vị trí registry vật lý không bao giờ đi vào mã nguồn được viết. Việc các byte của thư viện được phục vụ từ đâu (một thư mục catalog cục bộ, bộ nhớ đệm nội dung, hay một registry từ xa) là việc của trình phân giải, được gắn kết tại thời điểm phân giải; di dời một registry là thay đổi cấu hình trình phân giải, không phải thay đổi mã nguồn.
Các từ khóa JSON Schema bị cấm
Các từ khóa JSON Schema 2020-12 $dynamicAnchor và $dynamicRef bị cấm trong các mục của SchemaLibrary. Trình phân tích cú pháp SchemaLibrary quét cả các mục schema lẫn phần thân template tại thời điểm tải workspace; publishing-linter áp dụng một lớp bảo vệ dự phòng tại thời điểm xuất bản; công cụ khởi tạo quét lại phần thân đã được phân giải sau khi thay thế tham số, nên một template lén đưa các từ khóa bị cấm vào qua giá trị tham số vẫn thất bại. Ba lượt quét này cùng nhau chặn con đường đưa vào tĩnh ($dynamicAnchor dạng literal trong một mục schema hoặc phần thân template), con đường đưa vào qua tham số (một giá trị $args: chứa $dynamicRef), và con đường vượt qua bằng công cụ ngoài luồng (lớp bảo vệ lúc xuất bản bắt được mọi thứ đã bỏ qua trình phân tích cú pháp).
Khi việc từ chối xảy ra, lỗi sẽ nêu từ khóa vi phạm và đường dẫn tệp. Tác giả thấy lỗi ngay tại thời điểm soạn thảo thay vì ở lần khởi tạo đầu tiên; phần thân template không được miễn khỏi lượt quét lúc tải.
Ngữ nghĩa tham chiếu động gắn với việc đánh giá lúc chạy theo những cách phá vỡ cam kết về tính tất định tại thời điểm biên dịch của trình biên dịch. Những tác giả cần hành vi tham chiếu động sẽ cấu trúc lại schema để dùng phân giải $ref tĩnh; bước kiểm tra này không có ngoại lệ.
Vị trí cấp bậc
SchemaLibrary thuộc Tier 3 trong mô hình tài liệu phân cấp thực thể — là tùy chọn dành cho các catalog cần tái sử dụng schema giữa các Component. Các catalog không có nội dung schema lặp lại được phát hành mà không cần bất kỳ thực thể SchemaLibrary nào; việc đánh dấu cấp bậc báo hiệu “nâng cao; bỏ qua nếu không cần” cho mục đích điều hướng tài liệu, chứ không phải về khả năng. Trình biên dịch xử lý SchemaLibrary đồng nhất với các loại thực thể catalog khác: cùng cơ chế kiểm tra envelope khi tải workspace, cùng pipeline JSON Schema 2020-12 cho nội dung của từng mục, cùng pipeline phát hành OCI tại thời điểm release.
Trong Tier 3, bản thân cơ chế helper tham số hóa spec.templates cũng là tùy chọn. Các thư viện có nhiều cấu trúc lặp lại đáng kể (một template Probe được tham số hóa theo port + path; một template CORS được tham số hóa theo allowed-origins; một template TLS được tham số hóa theo đường dẫn cert + key) sẽ có lợi khi tái sử dụng qua templates; các thư viện có các mục đa dạng, dùng một lần thì bỏ qua hoàn toàn khối templates và viết trực tiếp từng mục dưới spec.schemas.