Soạn thảo dạng rút gọn
Dạng rút gọn là một cách viết tắt khai báo có hình dạng YAML cho JSON Schema 2020-12. Tác giả viết các ràng buộc cho từng trường dưới dạng map YAML inline-flow (port: { type: integer, min: 1, max: 65535, default: 8080 }); các nút đối tượng trung gian là lồng YAML tự nhiên; tham chiếu dùng $ref: tiêu chuẩn của JSON Schema. Trình biên dịch chuyển đổi dạng rút gọn sang JSON Schema 2020-12 trước khi bất kỳ bước xác thực nào chạy, vì vậy việc xác thực, báo cáo lỗi và mọi công cụ đọc schema đều hoạt động trên JSON Schema đã được phân giải, bất kể nó được soạn ở dạng nào.
Trang này mô tả bộ từ vựng của dạng rút gọn, các quy ước cấu trúc, cơ chế phân biệt đối tượng suy luận và tường minh, ngữ nghĩa đóng, tính không đồng nhất của type: cho phép mảng các kiểu được phép, các từ khóa dành riêng ở mọi phạm vi dạng suy luận, và không gian tên mở rộng x-aggrega-*. Về ngữ nghĩa phân giải $ref: giữa các tài liệu, xem cross-document-ref.md. Về ngữ pháp soạn thảo khối assertions, xem templates/assertions-block.md. Về tập trụ dữ liệu (values:, infra:, provides:, uses:, features:, locals:, parameters:), xem data-pillars.md.
Dạng rút gọn là bề mặt soạn thảo mặc định cho schema:, parameters: và các mục SchemaLibrary. JSON Schema YAML là một lựa chọn soạn thảo ngang hàng; cả hai dạng đều là hạng nhất và có thể được trộn lẫn trong cùng một schema. Hai dạng biên dịch ra cùng một tài liệu JSON Schema đã phân giải; công cụ và bước xác thực phía sau không phân biệt cách soạn thảo.
Từ vựng
Các từ khóa của dạng rút gọn là những từ khóa trong các bảng dưới đây. Tác giả học chúng một lần và áp dụng cho schema:, parameters: và các mục SchemaLibrary.
Từ khóa kiểu và định danh
| Từ khóa | Ý nghĩa | Biên dịch thành JSON Schema |
|---|---|---|
type | Kiểu của trường (string, integer, number, boolean, object, array, hoặc một mảng các kiểu được phép) | type: |
description | Tài liệu mô tả dễ đọc | description: |
default | Giá trị mặc định khi trường bị thiếu | default: |
required | Dấu đánh trên từng lá (required: true) cho các trường bắt buộc phải có | Thêm tên trường vào mảng required: của nút cha |
Từ khóa ràng buộc
| Từ khóa | Ý nghĩa | Biên dịch thành JSON Schema |
|---|---|---|
enum | Các giá trị được phép (danh sách) | enum: |
const | Giá trị duy nhất được phép — một giá trị vô hướng, một map hoặc một danh sách | const: |
min | Giá trị tối thiểu (số) hoặc độ dài tối thiểu (chuỗi/mảng) | minimum: (số); minLength: (chuỗi); minItems: (mảng) — chọn theo type: |
max | Giá trị hoặc độ dài tối đa, tương ứng với min | maximum: / maxLength: / maxItems: |
minLength / maxLength | Ràng buộc độ dài chuỗi tường minh | Ánh xạ trực tiếp sang minLength: / maxLength: (dùng khi min/max có thể gây nhập nhằng) |
pattern | Mẫu regex cho chuỗi | pattern: |
format | Định dạng có tên mà một chuỗi phải tuân theo — một trong email, uri, hostname, ipv4, ipv6, uuid, date-time, date (xem Các định dạng có tên) | format: |
Trên khối parameters: của một Aggregate, một số từ khóa này còn được kiểm tra trên chính phần khai báo, trước khi đọc bất kỳ giá trị Release nào. minLength và maxLength của chính một tham số phải bằng 0 trở lên — giá trị âm bị từ chối khi Aggregate được nạp — và mọi pattern, kể cả nằm trong một hợp đồng lồng items, properties hoặc valuesType, phải là một biểu thức chính quy biên dịch được, vì mẫu được biên dịch khi hợp đồng tham số được đọc. Mọi format, ở bất kỳ độ sâu nào, phải là một trong các định dạng có tên dưới đây. min hoặc max trên một tham số kiểu boolean hoặc object cũng bị từ chối, vì cặp này không giới hạn gì trên các kiểu đó. Mỗi lỗi sẽ dừng quá trình build và nêu tên tham số, dù có Release nào cung cấp nó hay không. Giới hạn độ dài bên trong một hợp đồng lồng không bị ràng buộc bởi mức sàn đó; xem entities/aggregate.md để biết mỗi bước kiểm tra chạy ở đâu.
Các định dạng có tên
format nêu dạng mà một giá trị chuỗi phải có. Các tên là những tên do đặc tả JSON Schema định nghĩa, viết đúng như đặc tả viết, và mỗi tên kiểm tra đúng ý nghĩa mà đặc tả định nghĩa:
| Tên | Giá trị hợp lệ là | Định nghĩa bởi |
|---|---|---|
email | một hộp thư: phần cục bộ (các atom phân cách bằng dấu chấm, hoặc một chuỗi trong ngoặc kép), @, rồi một tên miền hoặc một địa chỉ literal trong ngoặc vuông — ops@example.com. Tên hiển thị như Joe <joe@example.com> không phải là hộp thư | RFC 5321, mục 4.1.2 (Mailbox) |
uri | một URI tuyệt đối: scheme, :, rồi phần còn lại, với mọi ký tự nằm ngoài bảng chữ cái URI được mã hóa phần trăm — https://example.com/a%20b, s3://bucket/key. Một tham chiếu tương đối như /path thì không phải | RFC 3986 (URI) |
hostname | một tên máy chủ: các nhãn phân cách bằng dấu chấm gồm chữ cái, chữ số và dấu gạch nối, mỗi nhãn dài 1–63 ký tự, không bắt đầu hay kết thúc bằng dấu gạch nối, tổng cộng tối đa 253 ký tự — db-primary.data.svc.cluster.local. Nhãn Punycode (xn--…) được chấp nhận nguyên dạng; ký tự đại diện *, dấu gạch dưới hoặc dấu chấm ở cuối thì không | RFC 1123, mục 2.1 |
ipv4 | bốn số thập phân từ 0 đến 255, phân cách bằng dấu chấm — 192.0.2.1 | RFC 2673, mục 3.2 (dotted-quad) |
ipv6 | một địa chỉ IPv6 ở bất kỳ dạng văn bản nào — đầy đủ, rút gọn bằng ::, hoặc kết thúc bằng một địa chỉ IPv4 — 2001:db8::1. Zone (%eth0) hoặc độ dài tiền tố (/64) không thuộc về địa chỉ | RFC 4291, mục 2.2 |
uuid | 32 chữ số thập lục phân theo nhóm 8-4-4-4-12 phân cách bằng dấu gạch nối, chữ hoa hay chữ thường đều được — 2eb8aa08-aa98-11ea-b4aa-73b441d16380 | RFC 4122, mục 3 |
date-time | một dấu thời gian có độ lệch múi giờ — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, với ngày tồn tại trong tháng của nó, và giây nhuận chỉ ở 23:59 UTC | RFC 3339, mục 5.6 (date-time) |
date | một ngày lịch — 2026-09-28 — có ngày tồn tại trong tháng và năm của nó | RFC 3339, mục 5.6 (full-date) |
Một định dạng chỉ đánh giá chuỗi và không gì khác: giá trị thuộc kiểu khác do type của nó đánh giá. Và nó chỉ đánh giá cú pháp của giá trị — tên máy chủ không bao giờ được phân giải, URI không bao giờ được tải, hộp thư không bao giờ được liên hệ — nên phép kiểm tra cho cùng một kết quả ở mọi lần build và không cần mạng.
Phép kiểm tra chạy ở bất cứ đâu một giá trị được xác thực theo schema của nó: parameters: của một Aggregate, các values và infra mà các pillar schema: của một Component hay Feature ràng buộc, các values và infra theo từng cạnh mà schema payload của một socket usesSchema: ràng buộc, và mọi mục SchemaLibrary mà các schema đó tham chiếu tới. Tên định dạng của một pillar provides được đánh giá khi catalog được nạp, như mọi schema khác; các giá trị mà một Recipe công bố không được xác thực theo pillar, nên không định dạng nào được kiểm tra trên chúng. Bên trong allOf, anyOf, oneOf và not, một giá trị không đạt định dạng là một giá trị không đạt nhánh đó, giống hệt như một giá trị không đạt bất kỳ ràng buộc nào khác. Một giá trị không hợp lệ bị từ chối kèm tên trường, giá trị và định dạng.
Một tên nằm ngoài bảng sẽ bị từ chối khi schema được nạp, dù có giá trị nào tới được nó hay không, và thông báo từ chối liệt kê các tên được hỗ trợ — nhờ vậy một lỗi chính tả như emial trở thành một chẩn đoán thay vì một ràng buộc không kiểm tra gì. Với một mục SchemaLibrary, hãy chạy aggrega validate trên toàn bộ catalog để thấy tên bị lỗi: một Release có schema tham chiếu tới mục đó cũng bị từ chối, nhưng báo rằng không tìm thấy thư viện. password không phải là một định dạng: trường chứa dữ liệu bí mật nên khai báo sensitive: true thay vào đó.
Có một giới hạn áp dụng cho các dạng được tham chiếu gián tiếp. Khi dạng của một trường đến qua một $ref: mang kèm các từ khóa khác (chẳng hạn một map properties:), qua then: hoặc else: của một when:, hoặc qua một con trỏ vào một thuộc tính đã khai báo, thì format của nó được kiểm tra trên các trường mà dạng đó khai báo trực tiếp và qua allOf — nhưng không kiểm tra bên trong một nhánh anyOf, oneOf, not hoặc nhánh điều kiện nằm trong dạng đó.
Từ khóa kết hợp và tham chiếu
| Từ khóa | Ý nghĩa | Biên dịch thành JSON Schema |
|---|---|---|
$ref | Tham chiếu tới một fragment JSON Pointer hoặc một mục SchemaLibrary bên ngoài | $ref: |
allOf / anyOf / oneOf | Kết hợp JSON Schema | Cùng các từ khóa |
patternProperties | Map có khóa theo regex | Cùng từ khóa |
valuesType | Cách viết tắt cho các map có giá trị định kiểu (ví dụ: “object có mọi giá trị đều là chuỗi”) | additionalProperties: { type: <X> } |
Từ khóa vùng chứa
| Từ khóa | Ý nghĩa | Biên dịch thành JSON Schema |
|---|---|---|
items | Dạng phần tử của mảng | items: (dạng rút gọn đệ quy hoặc JSON Schema) |
properties | Khai báo con tường minh (hiếm khi cần; thường ngầm định qua cấu trúc YAML) | properties: |
additionalProperties | Có cho phép các thuộc tính chưa khai báo hay không (false trên một đối tượng dạng suy luận, nơi trình biên dịch tự thêm vào; trên một type: object tường minh thì bạn tự viết, và ở nơi bạn không viết, giá trị mặc định của chính JSON Schema là true được áp dụng) | additionalProperties: |
Từ khóa riêng của Aggrega
| Từ khóa | Ý nghĩa |
|---|---|
validate | Vị từ Go template trên từng trường trả về boolean; false sẽ dừng quá trình xác thực với validateMessage: |
validateMessage | Thông báo lỗi đi kèm khi validate: thất bại |
when | Áp dụng cây con có điều kiện; vị từ Go template quyết định các ràng buộc của nút có được áp dụng hay không |
sensitive | Khai báo rằng lá này chứa dữ liệu bí mật. Biên dịch thành x-aggrega-sensitive: true. Xem “Khai báo một lá là nhạy cảm” bên dưới |
$jsonschema | Lối thoát — nhúng một tài liệu con JSON Schema đầy đủ tại nút này |
$mode | Chú thích điều phối tùy chọn cho các trường hợp nhập nhằng (hiếm khi cần; xem “Dạng object suy luận và tường minh” bên dưới) |
Các từ khóa mượn từ JSON Schema ($ref, allOf, format, v.v.) dùng cú pháp giống hệt JSON Schema, nên tác giả đã biết JSON Schema sẽ nhận ra chúng ngay.
Một từ khóa có giá trị là dữ liệu sẽ mang giá trị đó đúng như đã viết. Một map hoặc danh sách được gán cho default, enum hoặc const chính là giá trị, không bao giờ là một schema lồng: endpoint: { type: object, default: { host: db, port: 5432 } } đặt mặc định của endpoint là đối tượng đó, và mode: { type: object, const: { kind: fast } } chỉ chấp nhận đúng đối tượng đó — mode: { const: { kind: fast } } cũng vậy, vì const, giống như enum, tự nó biến nút thành một lá. Điều tương tự cũng đúng bên trong một lối thoát $jsonschema:.
Cấu trúc của một leaf dạng compact
Đơn vị soạn thảo là một nút leaf — một trường kèm một dict ràng buộc:
field_name: { type: <type>, ...constraints... }Các mẫu thường gặp:
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 }Mỗi leaf nằm trên một dòng. Dict ràng buộc nắm bắt mọi thứ về hình dạng của trường; cấu trúc của nút cha nắm bắt vị trí của trường.
Đối tượng lồng nhau
Cấu trúc đối tượng phản ánh cách lồng nhau của YAML. Lồng sâu hoạt động trực tiếp, với mỗi lá vẫn nằm trên một dòng:
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 }Trình biên dịch suy ra cấu trúc đối tượng từ phân cấp YAML. Các nút trung gian (ở đây: primary, resources, requests, limits, auth) là các kiểu đối tượng chứa các nút con lồng bên trong. Trình biên dịch phát ra các khối type: object và properties: tường minh trong JSON Schema đã phân giải; tác giả không cần viết chúng.
Dạng đối tượng suy luận và dạng tường minh
Một phạm vi đối tượng dạng rút gọn có thể được viết theo hai cách:
Dạng suy luận — các phần tử con nằm trực tiếp dưới khóa cha, không có khai báo type: object:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true }Trình biên dịch nhận biết phạm vi này là một đối tượng vì các phần tử con của nó là các khai báo thuộc tính. Nó phát ra type: object, properties: { ... }, và tự động chèn additionalProperties: false tại thời điểm biên dịch. Ngữ nghĩa đóng là một phần của hợp đồng dạng suy luận: lỗi chính tả trong các trường do nhà phát triển viết sẽ thất bại một cách rõ ràng.
Dạng tường minh — khai báo type: object, liệt kê properties::
auth: type: object properties: username: { type: string, default: app_user } password: { type: string, sensitive: true } required: [password] additionalProperties: true # genuinely-open map authored on purposeTrình biên dịch KHÔNG chèn additionalProperties: false ở dạng tường minh. Tác giả khai báo type: object chịu toàn bộ trách nhiệm về quyết định đóng; dạng tường minh là nơi dành cho các map thực sự mở (additionalProperties: true) và cho các đối tượng cần những từ khóa JSON Schema khác (patternProperties, propertyNames, unevaluatedProperties).
Tiêu chí viết: dùng dạng suy luận cho các đối tượng đóng thông thường (trường hợp phổ biến trong các schema của catalog). Dùng dạng tường minh khi đối tượng cần thực sự mở, hoặc khi schema cần những từ khóa JSON Schema mà dạng rút gọn không trực tiếp hỗ trợ.
Ngữ nghĩa đóng
Theo quy ước, các đối tượng dạng suy luận của dạng rút gọn là đóng: các thuộc tính không được khai báo sẽ gây ra lỗi xác thực. Trình biên dịch tự động phát ra additionalProperties: false trên mọi phạm vi đối tượng dạng suy luận. Điều này phù hợp với nguyên tắc của catalog là lỗi đánh máy phải thất bại một cách rõ ràng.
Để mở một đối tượng (cho phép các thuộc tính bổ sung tùy ý), hãy dùng dạng tường minh với additionalProperties: true:
labels: type: object additionalProperties: true # opt-in; allow any string-keyed valuesVới mẫu phổ biến “đối tượng có mọi giá trị cùng một kiểu” (ví dụ, một map từ string → string cho nhãn), hãy dùng valuesType::
labels: { type: object, valuesType: string }nodeSelector: { type: object, valuesType: string }counters: { type: object, valuesType: integer }valuesType: <type> được biên dịch thành additionalProperties: { type: <type> }. Đây là mẫu đủ thường gặp để xứng đáng có một cách viết tắt bằng một từ khóa duy nhất.
Tên kiểu trần ở trên là cách viết cho schema: và SchemaLibrary. Trên một slot parameters: của Aggregate, hãy viết giá trị dưới dạng một contract — valuesType: { type: string }. Điều tương tự áp dụng cho hai từ khóa còn lại có giá trị bản thân là một contract, items: và mỗi mục dưới properties:, vì một khai báo tham số và mọi contract lồng bên trong nó đều mang cùng một hình dạng. Một tên kiểu trần ở bất kỳ vị trí nào trong ba vị trí đó trên một slot tham số sẽ bị từ chối, và chẩn đoán sẽ nêu tên contract lồng nhau nào đã chứa nó. Xem entities/aggregate.md để biết đầy đủ từ vựng của slot tham số.
Trường bắt buộc
Trường bắt buộc dùng required: true trên từng 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 }Trình biên dịch thu thập tất cả các dấu required: true trong một phạm vi đối tượng và phát sinh chúng thành mảng required: [field1, field2] của JSON Schema. Dấu này có hiệu lực ở bất cứ nơi nào thuộc tính được khai báo: trong một phạm vi dạng suy luận, và trên một thuộc tính bên trong một khối properties: tường minh.
Một bên sử dụng kéo một mục SchemaLibrary vào schema của mình qua $ref: có thể nêu các yêu cầu bắt buộc theo một trong hai cách — một mảng required: [name1, name2] ở cấp cha bên cạnh tham chiếu, hoặc một dấu required: true trên một thuộc tính mà nó khai báo dưới properties: tại đó. Xem cross-document-ref.md §“cú pháp required: dưới $ref: liên tài liệu” để biết quy tắc đầy đủ.
Mảng
Mảng dùng type: array cùng với items: mô tả cấu trúc của phần tử:
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 }Với trường hợp phổ biến “mảng các giá trị vô hướng có kiểu”, dạng nội tuyến chỉ cần một dòng. Với mảng các đối tượng, items: mở ra một schema dạng compact lồng bên trong.
Từ khóa type: — vô hướng hoặc mảng các kiểu
type: chấp nhận hoặc một giá trị đơn (type: string) hoặc một mảng các kiểu được phép (type: [string, integer, boolean]). Dạng mảng là cách diễn đạt chuẩn của JSON Schema 2020-12 cho “trường này chấp nhận một trong nhiều kiểu”:
release_tier: { type: [string, integer], description: "Numeric tier or named tag" }Khi type: mang một mảng, không gian giá trị là hợp của các không gian giá trị của những kiểu được nêu tên. Tác giả viết schema sử dụng dạng mảng phải xử lý cả hai dạng ở phía sau — trường type của JSON Schema đã được phân giải chứa hoặc một chuỗi hoặc một mảng, và các bên tiêu thụ duyệt qua schema đã phân giải sẽ kiểm tra cả hai dạng.
Các từ khóa dành riêng ở mọi phạm vi dạng suy luận
Cơ chế phân nhánh dạng suy luận nhận diện một tập nhỏ các từ khóa mang ý nghĩa ở cấp từ vựng dạng rút gọn: description, type, default, required, các từ khóa ràng buộc (enum, const, min, max, pattern, format, v.v.), và các từ khóa riêng của Aggrega (validate, validateMessage, when, sensitive). Khi bất kỳ từ khóa nào trong số này xuất hiện như một tên trường ở một phạm vi đối tượng dạng suy luận, trình biên dịch đọc phạm vi bao quanh như một lá ràng buộc thay vì một đối tượng: từ khóa được coi là một ràng buộc, không phải một thuộc tính con, và khi đó mọi khóa khác trong phạm vi đó cũng phải là từ khóa, nên khóa đầu tiên không phải từ khóa sẽ bị từ chối như một từ khóa không xác định.
sensitive đáng được nhắc đến riêng ở đây, vì đây là một cái tên hợp lý hơn nhiều cho một trường thực do nhà phát triển viết so với các từ khóa riêng khác của Aggrega. Một schema thực sự cần một thuộc tính có tên sensitive — chẳng hạn một component có values tự để lộ một cờ sensitive của riêng chúng — phải khai báo phạm vi bao quanh một cách tường minh, giống hệt như với một thuộc tính tên type hoặc default. Dạng tường minh bên dưới hoặc $mode: jsonschema trên phạm vi bao quanh đều đạt được điều đó: dưới $mode: jsonschema, toàn bộ nút được đọc như JSON Schema do tác giả viết, nơi sensitive là nội dung thông thường chứ không phải từ khóa dạng rút gọn.
Với các schema cần một thuộc tính được đặt tên theo một từ khóa dành riêng (ví dụ: một hợp đồng Component có trường description: do nhà phát triển viết, hoặc một trường type:, hoặc một trường default:), hãy dùng dạng tường minh cho phạm vi gây xung đột:
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: falseDạng tường minh bỏ qua cơ chế phân nhánh — properties: liệt kê các phần tử con một cách tường minh, nên xung đột từ khóa không phát sinh.
Ràng buộc này áp dụng ở mọi phạm vi dạng suy luận, theo cách đệ quy. Một đối tượng dạng suy luận lồng nhau chứa một thuộc tính được đặt tên theo một từ khóa dành riêng sẽ được đọc như một lá ràng buộc ở phạm vi đó. Cách khắc phục cũng vậy: chuyển phạm vi gây xung đột sang dạng tường minh.
Tham chiếu
Tham chiếu mượn $ref: của JSON Schema cả về cú pháp lẫn ngữ nghĩa:
resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }Các khối $defs: trong một schema dạng rút gọn khai báo các định nghĩa có thể tái sử dụng. Mỗi mục tự nó là một schema dạng rút gọn (hoặc JSON Schema, hoặc hỗn hợp). Tham chiếu qua fragment JSON Pointer #/$defs/<Name>:
Khai báo khối bên trong pillar có các trường tham chiếu đến nó, cạnh các trường đó — không phải cạnh pillar. Một khối schema: chỉ chấp nhận ba tên data-pillar ở cấp cao nhất của chính nó, nên một $defs: được viết ngang hàng với values: sẽ bị từ chối khi thực thể được nạp, kèm theo tên khóa vi phạm và tập pillar mà nó có thể chứa. Dù theo cách nào, con trỏ vẫn được viết là #/$defs/<Name>.
$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" }Về các tham chiếu liên tài liệu nhắm đến các mục SchemaLibrary, xem cross-document-ref.md. Về việc mở rộng dạng viết tắt URI OCI, xem uri-grammar.md.
Trỏ tham chiếu đến một định nghĩa, không phải đến một thuộc tính
Một con trỏ chỉ đến một mục $defs: — #/$defs/PodResources — là dạng nên dùng. Con trỏ hợp lệ ở bất cứ đâu JSON Schema cho phép, nên một con trỏ vào một thuộc tính đã khai báo cũng được chấp nhận và thực thi, nhưng lỗi được báo cáo kém chính xác hơn, và bạn nên biết sự khác biệt này trước khi viết một con trỏ như vậy.
Một trường có dạng lấy từ một mục $defs: được kiểm tra từng trường một: lỗi được báo cáo tại đường dẫn của giá trị thực sự sai, và mọi lỗi bên dưới trường đó đều được báo cáo, không chỉ lỗi đầu tiên.
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary: resources: { $ref: "#/$defs/PodResources" }Ở đây, một cpu sai được báo cáo tại primary.resources.requests.cpu.
Một trường có dạng lấy từ một con trỏ vào một thuộc tính đã khai báo được kiểm tra như một phần của toàn bộ tài liệu. Các ràng buộc vẫn áp dụng và tài liệu vi phạm chúng vẫn bị dừng — nhưng lỗi được báo cáo tại trường mang con trỏ thay vì tại giá trị bên trong nó, và khi nhiều trường như vậy cùng sai thì chỉ một trong số đó được nêu tên.
primary: resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary: resources: { $ref: "#/properties/primary/properties/resources" }Một cpu sai bên dưới secondary được báo cáo tại secondary.resources.
Cả hai cách viết đều chấp nhận và từ chối cùng các tài liệu, ngoại trừ một giới hạn về format được nêu trong Named formats: qua con trỏ, một format bên trong nhánh anyOf, oneOf hoặc not của dạng sẽ không được kiểm tra. Ngoài ra, điểm khác biệt là thông báo cho bạn biết được bao nhiêu, điều quan trọng nhất trong trình soạn thảo, nơi dấu đánh dấu được đặt theo đường dẫn đó. Điều tương tự áp dụng cho một mục $defs: mà con trỏ của chính nó lại trỏ ngược ra các thuộc tính: việc truy cập một định nghĩa qua nó sẽ thừa hưởng kiểu báo cáo kém chi tiết hơn.
Hình dạng có điều kiện qua when:
JSON Schema 2020-12 biểu đạt hình dạng có điều kiện qua if/then/else. Dạng rút gọn cung cấp when: như một cách viết tắt trực tiếp hơn: một vị từ Go template mà, nếu đúng, sẽ áp dụng các ràng buộc còn lại của nút; nếu sai, nút được xử lý như thể các ràng buộc của nó không tồn tại.
secondary: $ref: "#/$defs/NodePool" when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2 }Vị từ được đánh giá dựa trên các giá trị thể hiện của đối tượng cha. $ tham chiếu đến phạm vi đối tượng bao quanh. Khi architecture là replication, các ràng buộc (required: true, cùng ràng buộc bổ sung replicaCount: min: 2) được áp dụng thêm lên trên NodePool được tham chiếu. Khi architecture là standalone, các ràng buộc đó không có hiệu lực.
Vị từ có quyền truy cập các hàm Go template tiêu chuẩn (Sprig). Trình biên dịch biên dịch when: thành if/then/else của JSON Schema cùng với một lớp bao để đánh giá vị từ Go template trước khi quá trình xác thực chạy. Tính tất định được bảo toàn vì vị từ là thuần túy đối với thể hiện.
Kiểm tra hợp lệ tùy chỉnh theo từng trường qua validate: và validateMessage:
Một số ràng buộc không thể diễn đạt bằng min / max / pattern / enum. Với những trường hợp này, dạng rút gọn cung cấp validate: — một vị từ Go template mà, nếu sai, sẽ dừng việc kiểm tra hợp lệ với một lỗi tùy chỉnh.
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"Vị từ chạy trên giá trị của trường (truy cập bằng .); phạm vi đối tượng bao quanh là $. Nếu vị từ trả về false, việc kiểm tra hợp lệ tạo ra một lỗi dùng validateMessage: (hoặc một thông báo mặc định nếu không được cung cấp).
validate: xử lý các trường hợp nằm ngoài bộ từ vựng chuẩn của JSON Schema: kiểm tra hợp lệ ngữ nghĩa tùy chỉnh (kiểm tra định dạng semver, nội dung JSON của một chuỗi), các quy tắc liên trường nhưng phạm vi hẹp, trong đó ràng buộc của một trường phụ thuộc vào một trường anh em, và các ràng buộc không đáng để viết hẳn một khối assertions:.
validate: khác when: ở vai trò: when: bật tắt việc các ràng buộc có được áp dụng hay không; còn validate: tự nó là một ràng buộc.
Với các quy tắc thực sự liên trường có phạm vi rộng, nơi không có trường đơn lẻ nào là “trường đang được kiểm tra”, hãy dùng khối assertions: chuyên dụng. Xem templates/assertions-block.md.
Khai báo một lá là nhạy cảm — sensitive:
Một lá values, infra hoặc provides có thể khai báo rằng dữ liệu mà nó mô tả mang tài liệu bí mật:
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 được biên dịch thành từ khóa mở rộng x-aggrega-sensitive: true trên nút đó trong JSON Schema đã phân giải, cùng với các chú thích x-aggrega-* khác. Trình biên dịch đọc nó để suy ra những attachment nào trong một bản triển khai xử lý tài liệu được khai báo là nhạy cảm, và mang thông tin suy ra đó trên đồ thị đã biên dịch.
Hãy khai báo trên dữ liệu, không phải trên bộ định vị của nó. Sự phân biệt này là toàn bộ ý nghĩa của từ khóa và rất dễ bị hiểu ngược. Tài liệu của một thông tin xác thực là nhạy cảm; tên của tài nguyên chứa nó và khóa dữ liệu bên trong tài nguyên đó thì không — cả hai đều công khai, và cả hai đều được kết xuất ở dạng rõ vào mọi bên tiêu thụ tham chiếu đến tài nguyên. Đánh dấu một bộ định vị là khẳng định điều không đúng về nó và lan truyền lỗi đó đến mọi thứ phía sau có đọc khai báo. Trong ví dụ trên, origin được đánh dấu còn key thì cố ý không.
Phát biểu bổ sung — bất cứ thứ gì gắn vào điểm này đều xử lý tài liệu bí mật, bất kể phần điền khai báo gì về các lá của chính nó — hoàn toàn không phải là một khai báo lá. Đó là sensitive trên một khe attachment; xem entities/component.md “Attachment Slots”.
Khai báo cả một đối tượng là nhạy cảm
Từ khóa có thể đặt trên một đối tượng thay vì trên một giá trị vô hướng, và khi đó nó bao phủ mọi thứ bên dưới đối tượng đó — các con của chính đối tượng, và mọi thứ lồng sâu hơn nữa. Đây là khai báo nên dùng khi cả một khối là tài liệu nhạy cảm và việc đánh dấu từng lá riêng lẻ sẽ khiến lá tiếp theo mà ai đó thêm vào không được đánh dấu.
Các con của đối tượng phải nằm trong một khối properties: tường minh. Đây là nơi duy nhất mà dạng đối tượng suy luận không đáp ứng được, và lý do đáng để hiểu hơn là tìm cách lách qua:
spec: schema: values: credentials: type: object sensitive: true properties: # required here username: { type: string } password: { type: string }Viết các con ngay cạnh dấu đánh dấu, theo cách dạng đối tượng suy luận cho phép ở mọi nơi khác, sẽ bị từ chối khi biên dịch — con đầu tiên được báo là một từ khóa không xác định, với vị trí đặt trên khóa của chính con đó:
values: credentials: type: object sensitive: true password: # refused: unknown keyword "password" type: stringSự từ chối này là đúng, chứ không phải một hạn chế cần lách qua. Một nút được đọc là một lá ràng buộc ngay khi nó mang một từ khóa dạng rút gọn, và sensitive: là một từ khóa như vậy — nên từ thời điểm đó mọi khóa anh em cũng phải là từ khóa, mà password thì không phải. Khối properties: là thứ nói rằng “các khóa bên dưới là tên thuộc tính, không phải thêm từ khóa”, và đó cũng chính là cách phân định mà Dạng đối tượng suy luận so với tường minh mô tả. Hiểu chẩn đoán này là “dấu đánh dấu không thể đặt trên một đối tượng” là cách hiểu sai cần tránh: nó có thể, và khối này là cách bạn nói điều đó.
Một lá bên trong một đối tượng đã khai báo không cần dấu đánh dấu riêng. Thêm vào thì vô hại và không nói thêm điều gì mới, vì khai báo của đối tượng đã bao phủ nó.
Những gì từ khóa không làm
Cái tên dễ gợi ra những giả định mà từ khóa không đáp ứng, nên cần nói rõ giới hạn của nó:
- Nó không mã hóa bất cứ thứ gì. Nó là một chú thích trên một khai báo, không phải một cơ chế bảo mật.
- Nó không xác thực hay từ chối, trừ nơi các tham số của một template CloudFormation được điền. Không giá trị nào được chấp nhận hay bị từ chối vì một lá được khai báo là nhạy cảm, và không kết quả build nào thay đổi — ngoại trừ khi
valuesMappingcủa một Recipe hoặc FeatureRecipe CloudFormation đọc một lá được khai báo là nhạy cảm để điền các tham số của một template có nguồn, thì mọi giá trị literal mà mapping đó gắn sẽ dừng build, nên hai lần build chỉ khác nhau ở khai báo có thể kết thúc khác nhau. Xem A secret bound to a CloudFormation parameter would be written into the template (Một bí mật gắn vào một tham số CloudFormation sẽ bị ghi vào template). - Nó không đảm bảo rằng đầu ra được kết xuất không chứa tài liệu nhạy cảm. Việc một artifact có mang tài liệu nhạy cảm hay không phụ thuộc vào phần điền nào tác giả đã gắn và tác giả đã viết gì trong
valuescủa nó — xem architecture/08-credential-model.md “What the compiler does and does not guarantee”. Một giá trị được khai báo là nhạy cảm mà tác giả cung cấp trực tiếp sẽ được kết xuất giống hệt như một giá trị không khai báo, ở bất cứ nơi nào build có kết xuất nó. - Nó không ép buộc một cơ chế phân phối. Nó không thể biến một giá trị trực tiếp thành một tham chiếu kho lưu trữ, và nó không thu hẹp những gì danh sách cho phép
injectcủa một khe cho phép. - Nó không dừng build, ngoại trừ qua sự từ chối CloudFormation đó. Các thông báo khi build mà nó phát ra, được mô tả bên dưới, chỉ là khuyến nghị: build chạy đến hết và ghi các artifact của nó. Biến một thông báo thành lỗi nghiêm trọng là lựa chọn của một tổ chức, được thể hiện bằng một chính sách quản trị gắn vào build, chứ không phải điều từ khóa tự làm. Sự từ chối của provider CloudFormation ở trên là ngoại lệ: nó dừng build, vì một giá trị literal ghi vào template có thể bị đọc bởi bất kỳ ai đọc được stack.
- Nó không thay đổi byte kết xuất nào trên hầu hết các đích, và trên những đích đó sẽ không bao giờ thay đổi. Một nền tảng đích có khái niệm nhạy cảm riêng là nơi một khai báo có chỗ để đặt vào; một đích không có khái niệm đó thì không có gì để nó thay đổi, vĩnh viễn. Terraform là đích duy nhất trong thư viện chuẩn có nguyên thủy như vậy: khi đầu vào của một module được vendor nhận tài liệu mà tác giả khai báo là nhạy cảm, đầu ra được kết xuất có thêm một tệp ghi đè được sinh ra, khai báo thuộc tính nhạy cảm của chính Terraform cho đầu vào đó — xem providers/terraform.md “Declared-sensitive module inputs”. Ở mọi nơi khác, việc khai báo một lá là nhạy cảm trên một catalog hiện có giữ nguyên mọi artifact được kết xuất.
Những gì nó thay đổi trong đầu ra công cụ in ra
Điều duy nhất mà một khai báo có thay đổi là những gì công cụ in ra cho người đọc: đầu ra gỡ lỗi của nó, và văn bản của một lời từ chối, được mô tả bên dưới. Trên các bề mặt gỡ lỗi, một giá trị được khai báo là nhạy cảm được thay bằng văn bản cố định <redacted>:
- bản trace theo từng lượt mà
aggrega build --traceghi vào.trace/; - khối
Values:theo từng nút màaggrega inspectin ra cho một Aggregate; - khối attachment theo từng lá mà
aggrega inspectin ra cho một Release đã phân giải.
Khóa luôn được giữ lại và chỉ giá trị của nó bị thay thế, nên người đọc vẫn thấy rằng lá đó có được viết và có thứ gì đó đã bị giữ lại. Một lá mà tác giả không khai báo sẽ in giá trị của nó nguyên văn bên cạnh một lá anh em bị giữ lại — việc thay thế chỉ theo khai báo và không gì khác, nên một trường tên password không có khai báo sẽ được in, còn một trường đã khai báo tên key thì không.
Một khai báo tác động đến mọi lá bên dưới nó, và tác động đến cả ba bề mặt theo cùng một cách. Khi khai báo nằm trên một đối tượng, mỗi giá trị lồng bên trong đối tượng đó cũng bị giữ lại, ở bất kỳ độ sâu nào — khai báo của đối tượng gọi tên chúng, nên việc giữ lại chúng không khẳng định điều gì mà tác giả không viết. Việc so khớp dựa trên toàn bộ phân đoạn đường dẫn chứ không dựa trên văn bản, nên một lá anh em có tên chỉ bắt đầu bằng một tên đã khai báo sẽ không bị ảnh hưởng: khai báo dbPassword không giữ lại dbPasswordHint.
Việc giữ lại trong trace có thể tắt cho một lần build, khi giá trị bị giữ lại chính là thứ đang được gỡ lỗi: aggrega build --trace --trace-unredacted ghi các giá trị vào các tệp trace và đánh dấu mỗi tệp đó bằng một tiêu đề nói rõ điều này. Đây là lựa chọn tại thời điểm gọi lệnh, không có thiết lập cấu hình nào, nó chỉ tác động đến trace, và được ghi lại cùng cli/aggrega-build.md “Showing the withheld values”. Các bố cục của aggrega inspect có cờ riêng, --unredacted, được ghi lại cùng cli/aggrega-inspect.md “Showing the withheld values”.
Các giới hạn của hành vi đó quan trọng hơn chính hành vi.
Các artifact đã render không bao giờ bị che. Mọi thứ dưới dist/ được xuất ra đúng như quá trình render đã tạo, vì đó là thứ để triển khai: một placeholder ghi vào manifest sẽ là một bản triển khai hỏng chứ không phải một bản được bảo vệ. Việc che chỉ áp dụng cho những gì công cụ in ra, không bao giờ cho những gì nó ghi ra. Hiểu một khai báo như lời hứa rằng dist/ an toàn để công bố là cách hiểu sai duy nhất cần tránh — giới hạn nêu ở trên không thay đổi, và dist/ vẫn nhạy cảm ngang với attachment mang nhiều dữ liệu bí mật nhất của nó.
Có một điều một khai báo có thể thêm vào artifact đã render, và đó không phải là việc che: khi một đích có primitive về độ nhạy cảm của riêng nó, khai báo được render vào đó. Giá trị vẫn được ghi đầy đủ — không có gì bị giữ lại hay thay thế — và điều artifact có thêm là dấu đánh của chính đích đó bên cạnh giá trị, để công cụ của đích có thể xử lý giá trị như tác giả đã khai báo. Terraform là đích hiện cung cấp primitive như vậy, và những gì thuộc tính của nó đảm bảo và không đảm bảo được mô tả tại providers/terraform.md “Declared-sensitive module inputs”. Dấu đánh như vậy chỉ được mang theo khi danh tính của tên đã render được khôi phục từ chính khai báo; khi một template tự tạo ra tên, dấu đánh sẽ vắng mặt thay vì được ước đoán, vì đánh dấu một giá trị mà tác giả không khai báo sẽ khẳng định điều sai về nó. Khi template đó là một valuesMapping — của một Recipe, hoặc của FeatureRecipe thuộc một Feature gắn vào một component — bản build sẽ thông báo điều đó, như mô tả dưới đây.
Việc che áp dụng cho những gì khai báo nêu tên, cộng với những gì một template được thấy là đọc. Một leaf đã khai báo trong pillar values hoặc infra, và một delivery key mang dữ liệu bí mật từ một khóa provides được khai báo nhạy cảm, đều được nhận diện theo tên và bị giữ lại. Một giá trị do template tính ra nằm dưới một khóa không ai khai báo, nên thứ nhận diện nó là tham chiếu mà tác giả đã viết: trong trace, một mục locals: hoặc một trường source: có template đọc một leaf khai báo nhạy cảm sẽ bị giữ lại, và một mục locals: đọc một phần tử anh em đã bị giữ lại cũng vậy. Cách đọc này cố ý thận trọng — chạm tới cả một object là chạm tới mọi leaf đã khai báo bên dưới nó, và một template chuyển tiếp toàn bộ dữ liệu của mình là chạm tới tất cả chúng — nên một tham chiếu không phân giải được sẽ bị giữ lại thay vì được in ra.
Một tài liệu đã render được hiển thị dưới dạng render lại, và có nói rõ điều đó. Workload đã phân tích trong trace là một tài liệu do template của Recipe tạo ra: không có gì trong đó ghi lại mỗi ký tự đến từ khai báo nào, nên không có khóa nào để thay thế bên trong nó, và việc khôi phục liên kết theo từng trường sẽ đồng nghĩa với việc kiểm tra nội dung của một giá trị — điều trình biên dịch không làm. Thay vào đó, trace hiển thị chính template workload: được đánh giá lại trên một context mà dữ liệu khai báo nhạy cảm đã đọc là văn bản thay thế, kèm thông báo trong một mục workload_note bên cạnh tài liệu. Vì template thấy một chuỗi ở nơi vốn là chuỗi, bản render lại giữ nguyên hình dạng của tài liệu đã xuất và văn bản thay thế đứng đúng vị trí của dữ liệu bị giữ lại. Vẫn còn hai khác biệt và ghi chú nêu cả hai: một template rẽ nhánh theo nội dung của một giá trị sẽ render khác đi với văn bản thay thế, và một dữ liệu mà trục này không nêu tên được giữ nguyên. Đây là một góc nhìn gỡ lỗi về những gì đã render, không bao giờ là bản sao của nó.
Giá trị của một node được tiêu thụ bị giữ lại theo khai báo của chính node đó, trên cả hai bề mặt mà cạnh đưa chúng tới. Góc nhìn của một cạnh uses tái hiện những gì một component đích đã công bố, nên schema của chính đích chi phối nó: một khóa provides mà đích khai báo nhạy cảm sẽ bị giữ lại trong trace của bên tiêu thụ ngay cả khi bên tiêu thụ không khai báo gì. Khi khối inject của chính cạnh định tuyến khóa đó vào một delivery key của component tiêu thụ, delivery key đó cũng bị giữ lại — cùng quy tắc mà ánh xạ inject của một attachment tuân theo, đọc cùng khai báo, nên hai cách nối không thể mâu thuẫn. Các bố cục của aggrega inspect hiển thị pillar và attachment của chính một node, chứ không phải giá trị đã công bố của node được tiêu thụ, nên không có gì ở đó mang góc nhìn liên node cần giữ lại.
Một attachment viết trên một kết nối bị giữ lại theo khai báo của chính Feature của nó, trên mọi bề mặt hiển thị nó. Trace hiển thị nó dưới góc nhìn cạnh uses của kết nối đó, tại .context.uses.<alias>.features.<slot>, và aggrega inspect in nó bên dưới dòng của kết nối trong một Release đã phân giải. Trên cả hai, một leaf values hoặc infra mà Feature của nó khai báo nhạy cảm bị giữ lại đúng như với cùng Feature đó gắn trực tiếp vào component, và trong trace, một khóa thuộc provides đã phân giải của attachment mà Feature khai báo nhạy cảm cũng bị giữ lại. Kiểu, phiên bản, nhãn và mọi leaf cùng khóa provides không được khai báo đều in nguyên văn, nên một locator đã công bố vẫn đọc được bên cạnh dữ liệu bí mật mà nó định vị. Một slot khai báo sensitive: true, trên component hoặc trên một socket, đánh dấu attachment là xử lý dữ liệu bí mật và không tự giữ lại leaf nào — việc leaf nào bị giữ lại là do Feature khai báo.
Các phép chiếu máy đọc được là nguyên văn theo hợp đồng, và cần được xử lý giống như các tệp mà chúng xuất phát. aggrega inspect --raw xuất một thực thể đúng như đã viết, và aggrega inspect --output yaml tái hiện thực thể đã viết cho mọi kind, kể cả Release. Không lệnh nào thay thế gì, và điều đó là cố ý: đây là những đầu ra mà script phân tích và diff so sánh, nên một đầu ra lặng lẽ giữ lại một phần của nó sẽ trình bày sai đầu vào mà nó tuyên bố tái hiện và phá vỡ vòng khứ hồi mà các bên tiêu thụ dựa vào. Khai báo một leaf là nhạy cảm không đủ để giữ nó khỏi các đầu ra đó: hãy pipe, lưu trữ và chia sẻ chúng theo cách bạn làm với chính Aggregate và Release.
Đồ thị đã biên dịch là phép chiếu máy đọc được duy nhất có giữ lại, ở bất cứ nơi nào nó được cung cấp. --ir-graph, trên aggrega inspect, aggrega validate và aggrega build, ghi đồ thị mà lần chạy đã phân giải dưới dạng JSON bên cạnh những gì lệnh vốn tạo ra, và aggrega/irGraph của daemon trả về cho trình soạn thảo cùng đồ thị đó; trong mỗi trường hợp, một giá trị mà tác giả khai báo nhạy cảm được thay thế đúng như trong các bố cục dễ đọc. --unredacted đặt cạnh --ir-graph sẽ in các giá trị đó, và trường unredacted trong yêu cầu gửi daemon cũng vậy. Vì thế, đồ thị đọc từ một lệnh và đồ thị đọc qua giao thức của daemon là cùng một tài liệu theo cùng một quy tắc xử lý, và một pipeline hay client cần các giá trị đã viết phải yêu cầu chúng.
Một lời từ chối nói gì về một giá trị đã khai báo
Một lời từ chối do một template đọc một giá trị mà tác giả đã khai báo là nhạy cảm đưa ra sẽ không mang theo giá trị đó. Khi một template dừng bản build — một assertion gọi fail, một biểu thức không thể đánh giá, đầu ra không đọc được thành tài liệu mà template phải tạo ra — và một trong các tham chiếu của nó chạm tới một dữ liệu được khai báo là nhạy cảm, thì nội dung được báo cáo đến từ việc đánh giá cùng template đó lần thứ hai, trên một ngữ cảnh trong đó mọi dữ liệu được khai báo là nhạy cảm đều đã đọc là <redacted> — trừ khi template dừng ở một câu do chính nó viết ra đầy đủ, tức trường hợp đầu tiên dưới đây:
assertion failed: the admin password <redacted> must be supplied as a reference- Một
failcó câu được viết đầy đủ trong template sẽ được báo cáo đúng như đã viết. Khi lời gọi đã dừng bản build làfailnhận một chuỗi trong ngoặc kép —fail "…", không có gì được truyền qua pipe vào nó và không có gì được ghép vào câu của nó — thì lời từ chối mang theo câu đó bất kể giá trị chứa gì và bất kể nhánh nào dẫn đến lời gọi, vì câu đó không trích dẫn bất cứ thứ gì template đã đọc: một assertion từ chối một nguồn gốc có dạng sai sẽ hiển thị lời giải thích riêng của nó về dạng đó. Một câu được tạo theo bất kỳ cách nào khác —printf, một trường, một biến, một giá trị được truyền qua pipe vàofail— được báo cáo theo các trường hợp tiếp theo. - Khi lần đánh giá thứ hai thất bại tại cùng biểu thức vì cùng lý do, lỗi của nó là lỗi được báo cáo. Câu do chính tác giả viết được giữ nguyên, với
<redacted>ở chỗ giá trị từng đứng, và một giá trị mà template đã mã hóa, đặt trong dấu nháy hay biến đổi theo cách khác cũng bị che giấu, vì việc thay thế xảy ra trước khi biến đổi. - Khi không như vậy, lời từ chối nêu tên biểu thức thất bại và cho biết văn bản của nó bị che giấu. Đó là một template có hành vi phụ thuộc vào nội dung giá trị — nó đi theo nhánh khác, hoặc thất bại ở chỗ khác, trên văn bản thay thế — nên không thứ gì nó tạo ra có thể được hiển thị. Để một lời từ chối như vậy tự giải thích, hãy viết đầy đủ câu của nó trong lời gọi
fail, như trường hợp đầu tiên mô tả. Lời từ chối vẫn dừng bản build, và vẫn giữ mã của nó. - Một Workload đã render mà schema Workload từ chối được diễn đạt dựa trên schema. Các trường của tài liệu không mang liên kết nào ngược về dữ liệu mà template của nó đã đọc, nên khi template đó đọc một dữ liệu được khai báo là nhạy cảm, mọi phát hiện có thể trích dẫn một giá trị sẽ nêu ràng buộc thay vào đó, với
<redacted>ở vị trí của giá trị và một thông báo giải thích lý do. Không có lời khuyên nào suy ra từ giá trị được đưa ra, và một phát hiện không trích dẫn giá trị nào — một key bị thiếu, một key mà Workload không chấp nhận — vẫn đọc như mọi khi:
.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)- Đầu vào
withcủa một bước pipeline bị hợp đồng đầu vào đã khai báo của bước đó từ chối được diễn đạt dựa trên hợp đồng khi templatewithđọc một dữ liệu được khai báo là nhạy cảm: từng vị trí thất bại trong đầu vào và keyword của schema đã từ chối nó, kèm theo một thông báo giải thích lý do, và không gì mà đầu vào mang theo. - Một lời từ chối nêu tên một tọa độ
source:được diễn đạt dựa trên những gì không phải do khai báo tạo ra khi một templatesource:tạo ra tọa độ đó bằng cách đọc một dữ liệu được khai báo là nhạy cảm — nguồn không có trong lockfile hoặc cache, archive đã cache của nó không khớp với những gì lockfile ghi lại, hoặc pin được ghi bên cạnh entity không khớp với lockfile. Mọi dòng mà một lời từ chối như vậy in ra đều nêu các tọa độ mà việc tra cứu đã dùng, nên nó nêu nguồn theo url và phiên bản hoặc tham chiếu mà nó được yêu cầu — ở chỗ nó đã đọc chúng — với<redacted>đại diện cho từng tọa độ mà một template như vậy tạo ra, và cho biết lý do của nó bị che giấu. Nó giữ mã của mình và cách khắc phục mà bản build đưa ra cho mã đó:
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 producedNhững gì được tính là đã khai báo là những gì các khai báo nêu tên, trên mọi phần của ngữ cảnh mà một template có thể đọc: values và infra của chính component, các Features gắn vào nó và vào từng kết nối của nó, một delivery key mang dữ liệu đã khai báo, một key provides mà Component của nó khai báo là nhạy cảm, từng mục của một danh sách mà ngữ cảnh mang, được mô tả bên dưới, và một mục locals: được tính từ bất kỳ thứ nào trong số đó. Một template không đọc thứ nào trong số đó báo cáo chính xác như khi không có khai báo nào ở bất cứ đâu, từng byte một, nên chỉ lời từ chối do một template đã đọc một giá trị đã khai báo đưa ra mới được báo cáo khác đi. Cách đọc này giống cách trace sử dụng, đọc từ các tham chiếu mà template viết ra: chạm tới cả một object là chạm tới mọi leaf đã khai báo bên dưới nó, nên nó có thể che giấu văn bản không chứa giá trị nào. Một template chuyển tiếp toàn bộ dữ liệu của nó cùng lúc — dấu chấm hoặc $ không có gì theo sau, được truyền cho một hàm như toJson, được in ra, hoặc được chuyển cho một template mà nó gọi theo tên — đọc mọi giá trị đã khai báo trong đó, nên lời từ chối của nó được báo cáo theo cùng cách; bên trong thân range hoặc with, dấu chấm là giá trị mà thân đó lặp qua hoặc đặt tên, và chuyển tiếp nó chỉ đọc những gì giá trị đó chứa. Không có gì ở đây phụ thuộc vào --trace-unredacted: flag đó chỉ tác động tới các tệp trace, và một lời từ chối đọc giống nhau dù có hay không có nó.
Một giá trị đã khai báo bị che giấu ở bất cứ nơi nào nó nằm, kể cả bên trong một danh sách. Các mục của một danh sách chịu sự chi phối của những thực thể khác nhau, và mỗi mục bị che giấu theo khai báo của thực thể riêng của nó. Trên view .boundary mà một FeatureRecipe phạm vi toàn boundary đọc, mỗi kết nối được liệt kê trong internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges và cross_boundary_uses_edges mang provides mà target của nó công bố, bị che giấu khi Component của target khai báo key đó là nhạy cảm, và mỗi mục của feature_attachments mang infra của attachment đó, bị che giấu khi Feature của nó khai báo leaf đó. Trên ngữ cảnh của một Feature gắn vào một component, mỗi mục của .context.used_by mang những gì component kết nối công bố, bị che giấu khi Component của component kết nối khai báo key đó. Cùng key đó trên một mục có thực thể không khai báo gì được trích dẫn nguyên trạng, và một mục locals: được tính từ một mục bị che giấu cũng bị che giấu theo. Lặp qua một danh sách, hoặc truy cập một trong các mục của nó qua index, là đọc toàn bộ danh sách, nên được tính là đọc những gì mọi mục mang:
error calling fail: target secret_ref "<redacted>" must start with ref-Điều đó tác động tới văn bản của một lời từ chối mà bản build đưa ra. Những gì một nhà cung cấp được cho biết về phần đầu vào nào của nó đến từ một giá trị đã khai báo — các giá trị mà một valuesMapping tạo ra, một tài liệu workload: đã kết xuất, mỗi mục artifacts:, mỗi trường của một mục omits: — không tính một giá trị được đọc từ bên trong một danh sách, nên cách chính nhà cung cấp xử lý một giá trị đã khai báo, kể cả lời từ chối của CloudFormation đối với một literal được gắn kết đã mô tả ở trên, không chạm tới giá trị đó.
Một số lời từ chối nằm ngoài phạm vi này. Văn bản do một plugin viết — lời từ chối riêng của một provider hoặc một bước pipeline — là câu của plugin, được giữ nguyên như plugin đã viết. Một template được đánh giá bên ngoài các assertion và quá trình render của bản build — nội suy tham số và kiểm tra tham số trong một Aggregate, các template when: và validate: của một schema, và việc phân giải một tọa độ source: có ghi lại pin của nó — báo cáo lỗi đúng như nó đã thất bại.
Cảnh báo build cho một giá trị được truyền dưới dạng literal
Một bản build in ra một cảnh báo cho mỗi delivery key mang dữ liệu được khai báo là nhạy cảm dưới dạng giá trị literal. Cảnh báo xuất hiện khi khối inject của một attachment định tuyến một key provides mà Feature của attachment đã khai báo là nhạy cảm lên một delivery key của component tiêu thụ, và giá trị thực sự được truyền đi:
warning: node "db" (provider "helm"): attachment "user_password" delivers a valuedeclared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where thetarget supports it, fill the slot with an attachment that delivers a reference insteadCó ba điểm về nó là có chủ ý.
Nó báo cáo cách một giá trị được truyền đi, không phải rằng có điều gì sai. Truyền một literal thường là thứ duy nhất mà một target chấp nhận, và cả một họ attachment tồn tại để làm đúng việc đó. Cảnh báo cho tác giả biết giá trị nào đi theo con đường đó và ở đâu, để lựa chọn trở nên hiển hiện thay vì ngầm định; nó không khẳng định lựa chọn đó là sai lầm.
Nó là một cảnh báo và không bao giờ là một lần dừng. Bản build thành công và ghi các artifact của nó mà không thay đổi. Một tổ chức muốn một thông tin xác thực được truyền dưới dạng literal làm bản build thất bại sẽ thể hiện điều đó bằng một chính sách quản trị áp lên bản build, vốn là nơi một sự từ chối thuộc về — một quy tắc mà một số triển khai buộc phải phá vỡ không phải là mặc định của trình biên dịch.
Nó được quyết định từ cách nối dây, không bao giờ từ giá trị. Cảnh báo đọc độ nhạy cảm mà một schema đã khai báo cùng với việc truyền mà tác giả đã viết. Không giá trị nào được kiểm tra, nên một trường không bao giờ bị đoán là thông tin xác thực dựa vào tên hay nội dung của nó, và một giá trị không được khai báo mà tình cờ chứa mật khẩu thì không gây ra gì.
Có hai trường hợp cố ý giữ im lặng. Một delivery key mà key provides được tham chiếu không công bố gì thì không truyền literal nào và không báo cáo gì — cảnh báo theo sau một lần truyền đã thực sự xảy ra. Và một slot có allowlist inject rỗng sẽ để việc truyền cho Recipe, nên tác giả không viết delivery key nào để báo cáo và không có gì để xử lý.
Cảnh báo này là một lớp riêng, gắn với mã riêng của nó, và --no-unsupported-field-warnings không làm nó im lặng: flag đó bao phủ các thông báo về độ trung thực của một target, vốn là một phán đoán khác được làm im lặng vì những lý do khác. Nó cũng đến được trình soạn thảo, nơi nó hiện ra như một vấn đề trên Aggregate, bất cứ khi nào language server chạy với --build-on-inspect (hoặc config key serve.build_on_inspect) được bật. Thiết lập đó tắt theo mặc định để nhất quán với aggrega inspect: lệnh terminal không bao giờ tới giai đoạn render khi inspect một graph, nên nó cũng không đưa ra cảnh báo nào như vậy, và một lần inspect trong trình soạn thảo cũng không đưa ra cảnh báo nào thì đang cho bạn thấy đúng điều mà terminal cho thấy. Bật thiết lập là cách bạn yêu cầu trình soạn thảo thêm lớp bổ sung, và không có gì được ghi xuống đĩa khi bạn làm vậy — giai đoạn đó chạy và các artifact của nó bị loại bỏ. Nó thêm các cảnh báo mà một bản build đưa ra khi render, và không thêm kiểm tra nào khiến bản build dừng lại. Mọi vấn đề được công bố đều nêu tên lớp đã đưa ra nó, nên trình soạn thảo có thể tách cảnh báo này khỏi các cảnh báo mà giai đoạn phân giải và phân tích báo cáo.
Cảnh báo build cho một giá trị mà một ánh xạ render không có đánh dấu
Một lần build in ra một cảnh báo cho mỗi lá values được khai báo nhạy cảm mà một lần render không thể mang theo đánh dấu của nó trong khi tác giả vẫn nắm đòn bẩy đối với nó. Cảnh báo xuất hiện khi render từ một source: có các giá trị là đầu ra của một valuesMapping — của một Recipe, trên một lá mà Component của nó khai báo, hoặc của FeatureRecipe thuộc một Feature được gắn vào một component, trên một lá mà Feature đó khai báo. Các khóa đầu ra của ánh xạ là do chính nó đặt ra, nên không khai báo nào nêu tên bất kỳ khóa nào trong số đó và đích không nhận được đánh dấu theo từng khóa cho lá đó:
warning: node "api" (provider "terraform"): attachment "token": "values.token" is declaredsensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMappingwhose output keys no declaration names, so the target receives no per-key sensitivitymarking for it; ...Dòng cảnh báo nêu tên lá tại tọa độ được viết của nó và Recipe hoặc FeatureRecipe có ánh xạ chặn phép nối, vì khai báo và ánh xạ được viết trong hai thực thể khác nhau; dòng của một attachment bắt đầu bằng tên mà nó được gắn dưới đó, để hai attachment của cùng một Feature trên cùng một component được phân biệt. Gỡ bỏ ánh xạ chính là đòn bẩy: khi không có ánh xạ, các giá trị mà một lần render source nhận được có khóa là các đường dẫn lá đã khai báo, và đánh dấu đi cùng chúng. Một lần render chỉ artifact và một lần render chỉ workload không báo gì, vì chúng hoàn toàn không giao map giá trị nào cho đích, và một Feature được gắn vào một boundary cũng vậy, vì nó render trên một trụ values rỗng — giới hạn nêu trên là vĩnh viễn ở đó, và một cảnh báo sẽ không chỉ ra việc gì để làm. Giống như cảnh báo cho một giá trị truyền dưới dạng literal, đây là một cảnh báo và không bao giờ là một điểm dừng, nó không thay đổi byte nào được render, nó là một lớp riêng với mã riêng, sensitivity-not-conveyed, và --no-unsupported-field-warnings không tắt được nó. Cảnh báo và đầu ra linter trình bày đầy đủ dạng của nó.
Khai báo được đọc ở đâu, và không được đọc ở đâu
Từ khóa được đọc trên nút mà nó nằm, và việc đọc sau đó đi theo mọi đường mà một khai báo có thể đến được dữ liệu đó: các map thuộc tính lồng nhau, từng nhánh composition, và đích của một $ref. Một nhánh và một đích tham chiếu đều được hợp vào thuộc tính mang chúng, nên một khai báo tìm thấy qua một trong hai được thu thập cho thuộc tính đó; chỉ việc đi xuống properties mới kéo dài đường dẫn.
Một dấu đánh được đọc dù nó nằm cạnh một trong các từ khóa đó hay bên trong những gì từ khóa đó đến được, nên hai dạng sau không cần đặt có chủ đích:
- Cạnh một
$ref, hoặc bên trong đích của tham chiếu. Một dấu đánh trên lá tham chiếu khai báo lá đó. Một dấu đánh trong schema được tham chiếu cũng được thu thập cho lá tham chiếu, tại đường dẫn của lá đó cộng với chuỗi bên dưới — không bao giờ tại một đường dẫn bên trong định nghĩa, nơi không có giá trị nào được viết. - Cạnh một từ khóa composition (
allOf/anyOf/oneOf), hoặc bên trongpropertiesriêng của một nhánh. Một nhánh được hợp vào đối tượng mang nó, nên mọi nhánh đều được đi xuống — kể cả các nhánh điều kiện của một nút được viết bằng JSON Schema — và một khai báo bên trong một nhánh được thu thập tại đường dẫn riêng của thuộc tính hợp thành cộng với chuỗi của nó.
Một dạng thì cần đặt dấu đánh có chủ đích:
- Trên chính lá mảng, không phải trên kiểu phần tử
itemscủa nó. Một mảng có các phần tử mang dữ liệu bí mật được khai báo nhạy cảm tại mảng, vì kiểu phần tử không phải là một map thuộc tính và không được đi xuống.
parameters: là một bộ từ vựng khác
sensitive không thuộc bộ từ vựng hợp đồng có kiểu của parameters:. Một Aggregate khai báo nó trên một mục tham số sẽ bị từ chối khi Aggregate được nạp, với một chẩn đoán document-envelope báo unexpected property: "sensitive" (thuộc tính không mong đợi) đặt ngay trên khóa vi phạm — cùng cách xử lý mà bất kỳ khóa nào ngoài bộ từ vựng đó nhận được, vì hợp đồng tham số là một đối tượng đóng.
Sự bất đối xứng này là có chủ đích: trục nhạy cảm bao trùm ba trụ dữ liệu mà một thực thể catalog khai báo, còn một tham số là đầu vào hợp đồng môi trường chứ không phải một lá của trụ. Việc đưa dữ liệu thông tin xác thực lên qua một tham số được mô tả tại architecture/08-credential-model.md “Legacy charts that demand a formatted string”, nơi nêu sự đánh đổi mà cách đó tạo ra.
Kết hợp với allOf, anyOf, oneOf
Các từ khóa kết hợp hoạt động như trong JSON Schema:
# Inherit and extendsecondary: 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 }Trình biên dịch xuất ra cùng các từ khóa kết hợp đó trong JSON Schema đã phân giải. Mỗi mục kết hợp có thể là dạng rút gọn, JSON Schema, hoặc tham chiếu $ref:. Việc trộn lẫn trong cùng một phép kết hợp được hỗ trợ.
Lối thoát — $jsonschema:
Với những trường hợp vượt ra ngoài bộ từ vựng của dạng rút gọn ($dynamicRef, unevaluatedProperties, phép kết hợp not: lồng sâu, các kiểu đệ quy), bất kỳ nút nào cũng có thể chuyển xuống JSON Schema đầy đủ:
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 }Khối $jsonschema: chứa YAML của JSON Schema; trình biên dịch xử lý nó như một lối chuyển tiếp trong suốt — nội dung được đưa thẳng vào tài liệu JSON Schema đã phân giải tại vị trí của nút đó. Việc kiểm tra hợp lệ, báo lỗi và công cụ đều hoạt động trên tài liệu đã phân giải; lối thoát này thuần túy là một tiện ích khi soạn thảo.
Một nhánh not: có thể mang một description: cho biết vì sao hình dạng mà nó loại trừ bị từ chối. Khi đó, một giá trị khớp với nhánh này bị từ chối với mô tả đó làm lý do, được in trên một dòng, thay cho cách diễn đạt chung “not allowed here (không được phép ở đây)” — vì vậy hãy viết nó như câu mà tác giả của giá trị bị từ chối nên đọc. Chỉ mô tả được viết trên chính nhánh not: mới được dùng; mô tả trên một mục $defs mà nhánh chỉ tham chiếu tới thì không.
Mọi nút bên trong khối được đọc như JSON Schema, và một từ khóa dạng rút gọn viết ở đó vẫn giữ nghĩa rút gọn của nó (min: 3 trên một chuỗi vẫn là độ dài tối thiểu). Một $ref trong khối được phân giải như khi ở ngoài khối: #/$defs/Foo chỉ đến một mục trong $defs: của trụ cột, nên ví dụ khai báo Foo ở đó, và một tham chiếu chỉ đến một mục không ai khai báo sẽ bị từ chối khi thực thể được nạp. $dynamicRef được phân giải theo một $dynamicAnchor, nên có thể viết một cấu trúc đệ quy; một giá trị không hợp lệ nằm sâu trong phép đệ quy được báo cáo tại trường chứa nó — tree.children, với một name sai nằm sâu hai cấp trong một cây có các phần tử children là { $dynamicRef: "#node" }.
Có một giới hạn áp dụng cho unevaluatedProperties và unevaluatedItems. Khi được viết tại một nút đồng thời mang một tham chiếu, một từ khóa kết hợp (allOf, anyOf, oneOf), một điều kiện hoặc một schema phụ thuộc, cả hai đều được nạp nhưng không được thực thi — và unevaluatedItems cũng không được thực thi khi đứng cạnh contains. Trong ví dụ trên, unevaluatedProperties: false nằm cạnh allOf, nên { name: n, extra: 1 } được chấp nhận dù cả Foo lẫn patternProperties đều không khai báo extra.
Lối thoát $jsonschema: áp dụng theo từng nút, không phải theo từng tài liệu. Một schema có thể dùng dạng rút gọn cho các phần đơn giản, lối thoát JSON Schema cho một trường phức tạp duy nhất, và $ref: cho các hình dạng dùng chung — tất cả trong cùng một tài liệu.
Kết hợp dạng rút gọn và JSON Schema trong một tài liệu
Dạng rút gọn và JSON Schema có thể được kết hợp tự do tại bất kỳ ranh giới nút nào. Quy tắc điều phối dựa vào hình dạng của nội dung:
- Một nút chứa
$jsonschema:được xử lý như JSON Schema (lối thoát). - Một nút chứa các từ khóa cấp cao nhất theo kiểu JSON Schema (
type:,properties:,additionalProperties:,if:, v.v.) được xử lý như JSON Schema (dạng tường minh). - Một nút chỉ chứa các mục tên thuộc tính → schema con (không có từ khóa dành riêng của JSON Schema) được xử lý như dạng rút gọn (dạng suy luận).
- Một nút chỉ có
$ref:là một tham chiếu được chuyển tiếp nguyên vẹn. - Một nút có
allOf:/anyOf:/oneOf:là phép kết hợp; mỗi mục được điều phối độc lập.
Đối với các lá dạng rút gọn, mẫu tiêu chuẩn là field_name: { type: ..., constraints... } — một map YAML chứa từ vựng dạng rút gọn đã biết. Bộ điều phối nhận diện các dict ràng buộc qua các khóa của chúng.
Đối với trường hợp mơ hồ hiếm gặp (ví dụ: một schema dạng rút gọn có một trường được đặt tên đúng là type mà bộ điều phối dạng suy luận sẽ hiểu là từ khóa JSON Schema), dạng tường minh là cách khắc phục chuẩn — xem “Các từ khóa dành riêng ở mọi phạm vi dạng suy luận” ở trên.
Nhập một hợp đồng từ tệp — $import:
Một hợp đồng không nhất thiết phải nằm bên trong thực thể khai báo nó. $import: chỉ định một tệp để đọc hợp đồng từ đó:
spec: schema: $import: ./contracts/api-server.schema.yamlKhi đó toàn bộ spec.schema đến từ tệp đó, được viết giống hệt như khối mà nó thay thế — các trụ cột ở trên cùng, YAML dạng compact hoặc JSON Schema ở bên dưới:
values: greeting: { type: string, enum: [hello, howdy], default: hello }infra: image_tag: { type: string, default: "1.0" }provides: host: { type: string }Một trụ cột đơn lẻ có thể được nhập riêng, với các trụ cột anh em được viết trực tiếp bên cạnh nó:
spec: schema: values: $import: ./contracts/values.yaml infra: image_tag: { type: string, default: "1.0" }Dạng này cũng hoạt động tại valueSchema: và infraSchema: của một socket usesSchema:.
Các quy định chi phối nó:
$import:là khóa duy nhất tại vị trí nơi nó xuất hiện. Một khóa anh em được viết bên cạnh sẽ bị từ chối, thay vì một trong hai bị bỏ qua.- Một đường dẫn tương đối được đọc theo thư mục chứa tệp thực thể đã khai báo nó, không bao giờ theo thư mục nơi bản build chạy — cùng cơ sở mà
valuesMapping:,workload:vàartifacts:sử dụng. Nó phải nằm bên trong thư mục đó, vì mọi tệp mà một bản phát hành của thực thể mang theo đều được lấy từ đó: một đường dẫn leo ra ngoài thư mục, hoặc một đường dẫn tuyệt đối, chỉ định một tệp sẽ không đi cùng thực thể và bị từ chối — xem A path names content outside the entity’s own directory (Một đường dẫn chỉ định nội dung nằm ngoài thư mục riêng của thực thể). Một schema được nhiều thực thể dùng chung thuộc về một SchemaLibrary, được tham chiếu bằng$ref:. - Tệp được nhập đi cùng thực thể. Một thực thể đã xuất bản mang theo từng tệp mà schema của nó nhập, bao gồm mọi tệp của một chuỗi, để một bản sao được kéo từ registry đọc cùng hợp đồng và xác thực các giá trị được viết theo hợp đồng đó — xem
aggrega push. - Tệp được nhập chứa nội dung schema, không phải một tài liệu thực thể. Một tệp có nội dung không phải là một map YAML sẽ bị từ chối, kèm tên tệp.
- Bản thân một tệp được nhập có thể là một
$import:đơn lẻ, được phân giải đệ quy; một chuỗi quay lại một tệp đang được đọc sẽ bị từ chối, kèm tên chuỗi.
Việc nhập được đọc khi thực thể được tải, nên mọi bề mặt đọc thực thể đó đều thấy cùng một hợp đồng: aggrega validate, một bản build, aggrega push, aggrega inspect và trình soạn thảo. Một tệp không thể đọc, hoặc nội dung không phải là schema, sẽ bị từ chối tại thời điểm đó thay vì để hợp đồng không được thực thi — và một lần push sẽ từ chối nó trước khi bất cứ thứ gì được xuất bản.
$import: và $ref: không thể thay thế cho nhau. $import: chỉ định một tệp và thay thế toàn bộ nội dung; $ref: chỉ định một mục SchemaLibrary theo định danh và kết hợp tại bất kỳ nút nào. Một giá trị $import: mang định danh thư viện hoặc máy chủ registry sẽ bị từ chối, kèm hướng dẫn chuyển sang $ref:. Xem cross-document-ref.md.
Không gian tên mở rộng của Aggrega — x-aggrega-*
Dạng rút gọn nhận diện mọi từ khóa có tiền tố x-aggrega- là một phần mở rộng riêng của Aggrega. Không gian tên này là mở: các chú thích mới được đưa vào danh mục mà không cần sửa từ vựng cho từng từ khóa. Tác giả viết x-aggrega-selector, x-aggrega-narrowed-from hoặc các chú thích trong tương lai sẽ có nội dung được đặt đúng phạm vi trong JSON Schema đã phân giải mà không bị từ chối lúc biên dịch.
Tiền tố của không gian tên là quan trọng: một lỗi chính tả như x-agrega-source (thiếu một chữ g) KHÔNG được nhận diện là từ khóa mở rộng và sẽ bị từ chối bởi ngữ nghĩa đối tượng đóng ở các phạm vi dạng suy luận. Phạm vi tiền tố đóng vai trò như một lưới phát hiện lỗi chính tả cho bề mặt chú thích của danh mục.
Các chú thích x-aggrega-* cụ thể được trình biên dịch phát ra tại những điểm đã biết trong pipeline:
x-aggrega-selector:— được phát ra bởi quá trình tổng hợpusesSchema:vàfeaturesSchema:để mang chuỗi bộ chọn nhắm tới các Components nhà cung cấp tương thích.x-aggrega-sensitive:— được phát ra bởi một lá khai báosensitive: true. Xem Khai báo một lá là nhạy cảm ở trên.
Tác giả danh mục viết từ khóa mở rộng của riêng mình dùng cùng không gian tên này; công cụ phía sau tiêu thụ JSON Schema đã biên dịch đọc các khóa x-aggrega-* mà không xung đột với không gian từ khóa của chính JSON Schema.
Ví dụ minh họa — schema Component cho MariaDB
Một schema Component tiêu biểu ở dạng rút gọn cho kho dữ liệu MariaDB, sử dụng dạng suy luận xuyên suốt, kết hợp nhiều ràng buộc lá, các tham chiếu, hình dạng có điều kiện và một ví dụ oneOf cho khối xác thực:
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 }Nếu viết bằng YAML JSON Schema, cùng hợp đồng đó phải viết rõ type: object, properties: và additionalProperties: false cho mọi đối tượng, và liệt kê lại từng trường bắt buộc trong required: của cha, nên dài hơn đáng kể. Lợi ích về độ gọn tăng dần theo các hợp đồng Component lớn hơn và đủ đáng kể để dạng rút gọn trở thành bề mặt soạn thảo mặc định cho schema:, parameters: và các mục SchemaLibrary.
Tham chiếu chéo
- Về ngữ nghĩa phân giải
$ref:giữa các tài liệu (cú pháprequired:bên cạnh một tham chiếu liên tài liệu; mở rộng chuỗi từ thư viện sang thư viện; bên sử dụng thu hẹp thư viện): cross-document-ref.md. - Về ngữ pháp soạn khối
assertions:(các quy tắc liên trường màvalidate:ở dạng rút gọn không thể biểu đạt): templates/assertions-block.md. - Về tập trụ cột dữ liệu chứa các schema dạng rút gọn (
values:,infra:,provides:,uses:,features:,locals:,parameters:): data-pillars.md. - Về các quy tắc mở rộng cách viết tắt URI OCI (domain mặc định, phân đoạn registry, phiên bản dự phòng, mở rộng publisher): uri-grammar.md.
- Về việc soạn thực thể SchemaLibrary (nơi các schema có thể tham chiếu bằng
$ref:nằm trong catalog): ../entities/schemalibrary.md.