Phân giải `$ref:` xuyên tài liệu
Trang này mô tả ngữ nghĩa phân giải của các tham chiếu $ref: xuyên tài liệu trong bề mặt soạn schema của Aggrega — những gì tác giả của Components, Features và các mục SchemaLibrary thấy khi một $ref: vượt qua ranh giới tài liệu để trỏ vào một thư viện, cùng các quy tắc required: theo từng cú pháp, xác định những dạng soạn thảo nào hoạt động trơn tru với việc mở rộng xuyên tài liệu.
$ref: là thành phần gốc của JSON Schema 2020-12. Nó xuất hiện bên trong nội dung schema: (các mục Component, Feature, SchemaLibrary), bên trong các schema dạng rút gọn, và bên trong lớp JSON Schema được tổng hợp mà usesSchema: và featuresSchema: sinh ra. Trang này tập trung vào trường hợp xuyên tài liệu, khi $ref: trỏ tới một mục SchemaLibrary nằm trong một tệp hoặc một OCI artifact riêng.
Về kế thừa thực thể catalog (Component mở rộng Component), xem inheritance-and-interface.md. Một Release mở rộng một Release là một cơ chế khác, áp dụng trên một tài liệu không được lập chỉ mục trong catalog; cơ chế này được mô tả tại entities/release.md.
$import: là từ khóa còn lại truy cập nội dung bên ngoài tài liệu, và hai từ khóa này trả lời những câu hỏi khác nhau. $ref: chỉ định một mục trong một SchemaLibrary theo định danh — catalog phân giải nó, lockfile cung cấp phiên bản — và nó kết hợp được tại bất kỳ nút nào. $import: chỉ định một tệp nằm cạnh thực thể và thay thế toàn bộ nội dung bằng những gì tệp đó chứa. $import: áp dụng trên bề mặt schema cũng như tại valuesMapping:, workload:, artifacts: và parameters:; về $import: trên một schema, xem compact-form-authoring.md §“Nhập một hợp đồng từ tệp”.
Ngữ nghĩa phân giải $ref:
$ref: tuân theo cách phân giải chuẩn của JSON Schema 2020-12. Trong thực tế có các dạng tham chiếu sau:
- Fragment cục bộ trong cùng tài liệu:
{ $ref: "#/$defs/PodResources" }— phân giải tới mụcPodResourcesnằm dưới$defscủa schema. - Tham chiếu tới mục của SchemaLibrary theo định danh:
{ $ref: "WebPrimitives#/schemas/URL" }— dạng tên trần<Library>#/schemas/<Entry>. Tên thư viện được phân giải dựa trên catalog đã phân giải, và fragment JSON Pointer#/schemas/<Entry>chọn mục; phiên bản do lockfile cung cấp, không phải do tham chiếu. Một tham chiếu không mang host của registry — dạng có hostoci://<host>/…bị từ chối khi biên dịch với một chẩn đoán hướng tác giả tới dạng định danh, nhờ đó vị trí registry vật lý không bao giờ lọt vào mã nguồn do tác giả viết. 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 bộ phân giải, được gắn vào lúc phân giải, không bao giờ là một phần của tham chiếu. - Đường dẫn tệp không phải là đích tham chiếu:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }bị từ chối khi schema được biên dịch, với một chẩn đoán nêu tên dạng<Library>#/schemas/<Entry>. Nội dung schema được giữ trong một tệp bên cạnh thực thể thì được đưa vào bằng$import:, vốn bị giới hạn trong thư mục riêng của thực thể như mọi tệp mà thực thể đọc.
Tham chiếu được phân giải vào lúc biên dịch. Bộ mở rộng chèn trực tiếp nội dung được tham chiếu vào schema của bên sử dụng; IR được kết xuất mang nội dung đã chèn, không phải sự gián tiếp.
$ref: kết hợp tự nhiên với các từ khóa tổ hợp của JSON Schema:
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."allOf kết hợp dạng NodePool được tham chiếu với các ràng buộc bổ sung.
Cú pháp required: với $ref: liên tài liệu
Tác giả catalog chọn giữa hai dạng khai báo khi khai báo các thuộc tính bắt buộc trên một Component hoặc Feature: dấu đánh ở cấp lá (required: true trên từng thuộc tính) hoặc mảng ở cấp cha (required: [name1, name2, ...] ở phạm vi đối tượng). Cả hai dạng đều hợp lệ trong JSON Schema 2020-12, và cả hai đều có hiệu lực khi mở rộng $ref: liên tài liệu, nếu được viết ở vị trí mà phần này chỉ ra.
Khai báo dạng suy luận không có $ref: — các dấu đánh ở cấp lá được tích lũy tại thời điểm biên dịch. Trình biên dịch duyệt từng thuộc tính và, ở nơi một lá mang required: true, thêm tên thuộc tính vào mảng required: của đối tượng cha được tổng hợp.
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }Trình biên dịch xuất ra required: [database, display_name] ở phạm vi cha.
Các bên sử dụng có $ref: — bên cạnh một $ref: liên tài liệu chỉ được viết properties, required và description, và các yêu cầu bắt buộc mà bên sử dụng thêm vào là những gì nó viết ở đó: một mảng required: ở cấp cha, hoặc một dấu required: true ở cấp lá trên một thuộc tính mà nó khai báo dưới properties:. Các yêu cầu bắt buộc riêng của mục được tham chiếu — các dấu ở cấp lá trong dạng suy luận của nó, hoặc một mảng required: của chính nó — được áp dụng qua tham chiếu mà không thay đổi. Một mảng ở cấp cha nêu các yêu cầu bắt buộc mà không cần khai báo lại các thuộc tính mục đã khai báo:
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]Một dấu ở cấp lá cũng có hiệu lực, trên một thuộc tính mà bên sử dụng khai báo bên cạnh tham chiếu — nên properties: { database: { type: string, required: true } } viết ở đó khiến database trở thành bắt buộc giống hệt như required: [database]. Thuộc tính của bên sử dụng thay thế thuộc tính cùng tên của mục (xem Bên sử dụng thu hẹp mục thư viện), vì vậy hãy khai báo lại nó với cấu trúc bạn muốn.
Mở rộng chuỗi từ thư viện sang thư viện
Bản thân một mục SchemaLibrary có thể chứa một $ref: trỏ vào một mục SchemaLibrary khác, tạo thành một chuỗi. Trình biên dịch duyệt chuỗi này tại thời điểm biên dịch: mỗi $ref: gặp phải khi một mục được mở rộng cũng tự được mở rộng, theo ngữ cảnh của thư viện chứa nó.
# Library Aspec: schemas: DatabasePayload: type: object properties: host: { type: string } credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)spec: schemas: BasicAuth: type: object properties: username: { type: string } password: { type: string }Một Component tiêu thụ tham chiếu đến DatabasePayload nhận được hình dạng đã mở rộng hoàn toàn, với credentials được điền từ BasicAuth của thư viện B. Một giá trị vi phạm ràng buộc mà chuỗi đóng góp sẽ bị từ chối tại chính đường dẫn của nó trong tài liệu đang được kiểm tra, và lời từ chối không nêu tên mục thư viện mà ràng buộc đó đến từ; hãy lần theo chuỗi $ref: từ bên tiêu thụ để tìm ra nó.
Bên tiêu thụ thu hẹp mục thư viện
Một Component tiêu thụ có thể khai báo một thuộc tính có tên trùng với một thuộc tính được kéo vào từ một mục thư viện. Khi điều này xảy ra, thuộc tính đã biên dịch của bên tiêu thụ thay thế hoàn toàn thuộc tính của mục thư viện trong hình dạng đã hợp nhất.
# Library entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: schema: values: $ref: "Tools#/schemas/ToolContract" properties: side_effects: type: array items: { type: string, enum: [read] } default: [read]Trong hình dạng đã hợp nhất, side_effects phản ánh hợp đồng hẹp hơn của bên tiêu thụ (enum: [read], kèm một default); enum: [read, write, delete] rộng hơn của mục thư viện không còn nữa. Thuộc tính này do bên tiêu thụ tạo ra.
Đây là hành vi được mong đợi: việc bên tiêu thụ tinh chỉnh thuộc tính của một mục thư viện là mẫu thu hẹp chuẩn. Việc thu hẹp diễn ra âm thầm: thuộc tính của bên tiêu thụ đứng trên nguồn gốc riêng của nó.
Tham chiếu chéo
- Về kế thừa giữa các thực thể catalog (Component-extends-Component, Feature-extends-Feature), xem inheritance-and-interface.md.
- Về kế thừa giữa các tài liệu phía triển khai, vốn có các tham chiếu trỏ tới tệp thay vì thực thể catalog: một Release mở rộng một Release được mô tả tại
entities/release.md, và một Manifest mở rộng một Manifest tạientities/manifest.md. - Về các con trỏ nguồn riêng của từng provider (
Recipe.spec.source.chart:,Recipe.spec.source.modulePath:), xem tài liệu Recipe của từng thực thể. Các con trỏ nguồn của Provider không được hợp nhất dưới$ref:; plugin của provider sử dụng chúng trực tiếp. - Về các quy tắc mở rộng dạng viết tắt của URI OCI (domain mặc định, mở rộng thực thể theo ngữ cảnh, thứ tự ưu tiên phân giải, xử lý phiên bản), xem uri-grammar.md.