紧凑形式编写
紧凑形式是 JSON Schema 2020-12 的一种 YAML 形态的声明式简写。作者以行内流式 YAML 映射编写逐字段约束(port: { type: integer, min: 1, max: 65535, default: 8080 });中间对象节点即自然的 YAML 嵌套;引用使用 JSON Schema 标准的 $ref:。编译器在任何验证运行之前将紧凑形式转换为 JSON Schema 2020-12,因此无论 schema 以哪种形式编写,验证、错误报告以及每个读取 schema 的工具都基于解析后的 JSON Schema 工作。
本页介绍紧凑形式的词汇、结构约定、推断式与显式对象的分派、封闭语义、允许以数组列出多种许可类型的 type: 异构性、在每个推断形式作用域上保留的关键字,以及 x-aggrega-* 扩展命名空间。关于跨文档 $ref: 的解析语义,参见 cross-document-ref.md。关于断言块的编写语法,参见 templates/assertions-block.md。关于数据支柱集合(values:、infra:、provides:、uses:、features:、locals:、parameters:),参见 data-pillars.md。
紧凑形式是 schema:、parameters: 和 SchemaLibrary 条目的默认编写方式。JSON Schema YAML 是同等地位的编写选项;两种形式都是一等公民,并且可以在同一个 schema 中混用。两种形式编译为相同的解析后 JSON Schema 文档;下游工具和验证不感知编写方式。
词汇表
紧凑形式的关键字即下表所列。作者只需学习一次,即可在 schema:、parameters: 和 SchemaLibrary 条目中通用。
类型与标识关键字
| 关键字 | 含义 | 编译为 JSON Schema |
|---|---|---|
type | 字段类型(string、integer、number、boolean、object、array,或允许类型的数组) | type: |
description | 人类可读的文档说明 | description: |
default | 字段缺失时的默认值 | default: |
required | 逐叶节点标记(required: true),用于必须存在的字段 | 将字段名添加到父节点的 required: 数组中 |
约束关键字
| 关键字 | 含义 | 编译为 JSON Schema |
|---|---|---|
enum | 允许的值(列表) | enum: |
const | 唯一允许的值——标量、映射或列表 | const: |
min | 最小值(数值)或最小长度(字符串/数组) | minimum:(数值);minLength:(字符串);minItems:(数组)——由 type: 决定 |
max | 最大值或最大长度,与 min 对应 | maximum: / maxLength: / maxItems: |
minLength / maxLength | 显式的字符串长度约束 | 直接映射到 minLength: / maxLength:(在 min/max 存在歧义时使用) |
pattern | 字符串的正则表达式模式 | pattern: |
format | 字符串必须符合的命名格式——取 email、uri、hostname、ipv4、ipv6、uuid、date-time、date 之一(参见命名格式) | format: |
在 Aggregate 的 parameters: 块上,其中部分关键字还会在读取任何 Release 值之前,对声明本身进行检查。参数自身的 minLength 和 maxLength 须为零或正数——负值会在 Aggregate 加载时被拒绝——而每个 pattern(包括嵌套在 items、properties 或 valuesType 契约中的)都必须是能够编译的正则表达式,因为该模式在读取参数契约时即被编译。任何深度的每个 format 都必须是下文的命名格式之一。布尔或对象类型参数上的 min 或 max 同样会被拒绝,因为这一对关键字在这些类型上不约束任何内容。每种错误都会使构建停止,并指明相应参数,无论是否有 Release 提供该参数。嵌套契约内的长度界限不受此下限约束;各项检查在何处运行,参见 entities/aggregate.md。
命名格式
format 指定字符串值必须符合的形式。这些名称即 JSON Schema 规范所定义的名称,拼写与规范一致,每种格式检查的内容即规范对其的定义:
| 名称 | 符合要求的值为 | 定义来源 |
|---|---|---|
email | 一个邮箱地址:本地部分(以点分隔的原子,或带引号的字符串)、@,然后是域名或带方括号的地址字面量——ops@example.com。诸如 Joe <joe@example.com> 这样的显示名称不是邮箱地址 | RFC 5321,第 4.1.2 节(Mailbox) |
uri | 一个绝对 URI:协议名、:,然后是其余部分,URI 字符集之外的任何字符均经过百分号编码——https://example.com/a%20b、s3://bucket/key。诸如 /path 这样的相对引用不符合 | RFC 3986(URI) |
hostname | 一个主机名:由字母、数字和连字符组成的以点分隔的标签,每个标签 1–63 个字符,且不以连字符开头或结尾,总长度最多 253 个字符——db-primary.data.svc.cluster.local。Punycode 标签(xn--…)按原样接受;通配符 *、下划线或末尾的点则不接受 | RFC 1123,第 2.1 节 |
ipv4 | 四个 0 到 255 之间的十进制数,以点分隔——192.0.2.1 | RFC 2673,第 3.2 节(点分四段) |
ipv6 | 任一文本形式的 IPv6 地址——完整形式、:: 压缩形式,或以 IPv4 地址结尾——2001:db8::1。区域标识(%eth0)或前缀长度(/64)不属于地址的一部分 | RFC 4291,第 2.2 节 |
uuid | 32 个十六进制数字,按 8-4-4-4-12 分组并以连字符分隔,大小写均可——2eb8aa08-aa98-11ea-b4aa-73b441d16380 | RFC 4122,第 3 节 |
date-time | 带偏移量的时间戳——2026-09-28T12:34:56Z、2026-09-28T12:34:56.5+02:00,日期须在当月实际存在,闰秒仅允许出现在 UTC 23:59 | RFC 3339,第 5.6 节(date-time) |
date | 一个日历日期——2026-09-28——其日期须在当年当月实际存在 | RFC 3339,第 5.6 节(full-date) |
格式只判定字符串,不判定其他:其他类型的值由其 type 判定。并且它只判定值的语法——从不解析主机名、从不获取 URI、从不联系邮箱——因此该检查在每次构建中给出相同的结果,且无需网络。
凡是根据 schema 验证值的地方,都会运行该检查:Aggregate 的 parameters:、Component 或 Feature 的 schema: 支柱所约束的 values 和 infra、usesSchema: 插槽的载荷 schema 所约束的逐边 values 和 infra,以及这些 schema 所涉及的每个 SchemaLibrary 条目。provides 支柱的格式名称会在目录加载时像其他 schema 一样被判定;Recipe 发布的值不会根据该支柱进行验证,因此不会对其检查任何格式。在 allOf、anyOf、oneOf 和 not 内部,不符合格式的值即为不满足该分支的值,与不满足任何其他约束的值完全相同。不符合的值会被拒绝,并指明字段、值和格式。
表外的名称会在 schema 加载时被拒绝,无论是否有值涉及它,且拒绝信息会列出受支持的名称——因此诸如 emial 这样的拼写错误会产生诊断,而不是成为一个什么也不检查的约束。对于 SchemaLibrary 条目,请对整个目录运行 aggrega validate 以查看出错的名称:schema 涉及该条目的 Release 同样会被拒绝,但报告的是找不到该库。password 不是格式:携带机密材料的字段应改为声明 sensitive: true。
对间接获得的形式有一个限制。若字段的形式来自旁边带有其他关键字(例如 properties: 映射)的 $ref:,来自 when: 的 then: 或 else:,或来自指向已声明属性的指针,则其 format 会在该形式直接声明的字段上以及通过 allOf 进行检查——但不会在该形式内的 anyOf、oneOf、not 或条件分支中检查。
组合与引用关键字
| 关键字 | 含义 | 编译为 JSON Schema |
|---|---|---|
$ref | 对 JSON Pointer 片段或外部 SchemaLibrary 条目的引用 | $ref: |
allOf / anyOf / oneOf | JSON Schema 组合 | 相同的关键字 |
patternProperties | 以正则表达式为键的映射 | 相同的关键字 |
valuesType | 类型化值映射的简写(例如“所有值均为字符串的对象”) | additionalProperties: { type: <X> } |
容器关键字
| 关键字 | 含义 | 编译为 JSON Schema |
|---|---|---|
items | 数组元素的形式 | items:(递归的紧凑形式或 JSON Schema) |
properties | 显式的子节点声明(很少需要;通常通过 YAML 结构隐式表达) | properties: |
additionalProperties | 是否允许未声明的属性(在推断形式对象上为 false,由编译器添加;在显式的 type: object 上由你自行编写,未编写时适用 JSON Schema 自身的默认值 true) | additionalProperties: |
Aggrega 特有关键字
| 关键字 | 含义 |
|---|---|
validate | 逐字段的 Go 模板谓词,返回布尔值;为 false 时以 validateMessage: 停止验证 |
validateMessage | 伴随 validate: 失败的错误消息 |
when | 条件性子树应用;以 Go 模板谓词控制节点的约束是否生效 |
sensitive | 声明该叶节点携带机密材料。编译为 x-aggrega-sensitive: true。参见下文“将叶节点声明为敏感” |
$jsonschema | 逃生舱口——在此节点嵌入完整的 JSON Schema 子文档 |
$mode | 用于存在歧义情况的可选分派注解(很少需要;参见下文“推断式与显式对象形式”) |
借用的 JSON Schema 关键字($ref、allOf、format 等)沿用与 JSON Schema 完全相同的语法,因此已熟悉 JSON Schema 的作者可以立即认出它们。
值为数据的关键字按原样携带该值。 赋给 default、enum 或 const 的映射或列表就是值本身,绝不是嵌套的 schema:endpoint: { type: object, default: { host: db, port: 5432 } } 将 endpoint 的默认值设为该对象,而 mode: { type: object, const: { kind: fast } } 只接受恰好该对象——mode: { const: { kind: fast } } 也是如此,因为 const 与 enum 一样,本身就使该节点成为叶子。在 $jsonschema: 逃生舱口内部同样如此。
紧凑形式叶节点的结构
编写的基本单元是叶节点——一个带有约束字典的字段:
field_name: { type: <type>, ...constraints... }常见模式:
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 }每个叶节点占一行。约束字典描述字段形状的全部信息;父节点的结构则描述字段所在的位置。
嵌套对象
对象结构与 YAML 嵌套一一对应。深层嵌套可以直接使用,每个叶子仍然只占一行:
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 }编译器根据 YAML 层级推断对象结构。中间节点(此处为 primary、resources、requests、limits、auth)是包含嵌套子节点的对象类型。编译器会在解析后的 JSON Schema 中生成显式的 type: object 和 properties: 块;作者无需编写它们。
推断式与显式对象形式
紧凑形式的对象作用域有两种编写方式:
推断形式——子项直接位于父键之下,不声明 type: object:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true }编译器之所以将该作用域识别为对象,是因为其子项都是属性声明。编译时,它会生成 type: object、properties: { ... },并自动注入 additionalProperties: false。封闭语义是推断形式契约的一部分:开发者编写的字段中若有拼写错误,会明确报错。
显式形式——声明 type: object,并逐一列出 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 purpose在显式形式中,编译器不会注入 additionalProperties: false。声明 type: object 的作者需完全自行负责是否封闭对象;显式形式用于真正开放的映射(additionalProperties: true),以及需要其他 JSON Schema 关键字(patternProperties、propertyNames、unevaluatedProperties)的对象。
编写准则:普通的封闭对象(目录 schema 中的常见情形)使用推断形式。当对象应真正开放,或 schema 需要紧凑形式不直接支持的 JSON Schema 关键字时,使用显式形式。
封闭语义
按照约定,紧凑形式的推断形式对象是封闭的:未声明的属性会产生验证错误。编译器会自动在每个推断形式对象作用域上生成 additionalProperties: false。这符合目录中拼写错误应明确报错的准则。
要开放一个对象(允许任意附加属性),请使用显式形式并设置 additionalProperties: true:
labels: type: object additionalProperties: true # opt-in; allow any string-keyed values对于“所有值共享同一类型的对象”这一常见模式(例如用于标签的 string → string 映射),请使用 valuesType::
labels: { type: object, valuesType: string }nodeSelector: { type: object, valuesType: string }counters: { type: object, valuesType: integer }valuesType: <type> 会编译为 additionalProperties: { type: <type> }。这一模式足够常见,值得提供一个单关键字简写。
上面的裸类型名是 schema: 和 SchemaLibrary 中的写法。在 Aggregate 的 parameters: 槽位上,应改为将值写成契约:valuesType: { type: string }。另外两个值本身也是契约的关键字同样如此,即 items: 和 properties: 下的每个条目,因为参数声明及其内部嵌套的每个契约都采用同一种结构。在参数槽位上,这三个位置中任何一处出现裸类型名都会被拒绝,诊断信息会指出是哪个嵌套契约包含了它。完整的参数槽位词汇请参见 entities/aggregate.md。
必填字段
必填字段在每个叶子上使用 required: true:
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 }编译器会收集一个对象作用域内的所有 required: true 标记,并将其输出为 JSON Schema 的 required: [field1, field2] 数组。无论属性在何处声明,该标记都有效:在推断形式作用域中,以及在显式 properties: 块内的属性上。
通过 $ref: 将某个 SchemaLibrary 条目引入自身 schema 的使用方,可以用任一方式指明其必填项——在引用旁写父级的 required: [name1, name2] 数组,或在其于该处 properties: 下声明的属性上写 required: true 标记。完整规则参见 cross-document-ref.md §“跨文档 $ref: 下的 required: 语法”。
数组
数组使用 type: array,并通过 items: 描述元素的结构:
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 }对于“类型化标量数组”这一常见情况,内联形式只需一行。对于对象数组,items: 引入一个嵌套的紧凑形式 schema。
type: 关键字——标量或类型数组
type: 既接受单个值(type: string),也接受由允许类型组成的数组(type: [string, integer, boolean])。数组形式是 JSON Schema 2020-12 表达“该字段接受若干类型之一”的标准方式:
release_tier: { type: [string, integer], description: "Numeric tier or named tag" }当 type: 取数组时,值空间是所列各类型值空间的并集。编写使用数组形式的 schema 的作者必须在下游处理这两种形态——解析后的 JSON Schema 的 type 字段可能是字符串,也可能是数组,遍历解析后 schema 的使用方需检查这两种形态。
每个推断形式作用域中的保留关键字
推断形式的分派会识别一小组在紧凑形式词汇层面具有含义的关键字:description、type、default、required、约束关键字(enum、const、min、max、pattern、format 等),以及 Aggrega 特有的关键字(validate、validateMessage、when、sensitive)。当其中任一关键字作为字段名出现在推断形式的对象作用域中时,编译器会把外层作用域读作约束叶子而非对象:该关键字被视为约束,而不是子属性,并且该作用域中的其他每个键也必须是关键字,因此第一个不是关键字的键会作为未知关键字被拒绝。
这里需要特别提到 sensitive,因为与其他 Aggrega 特有的关键字相比,它更有可能被开发者用作真实字段的名称。如果某个 schema 确实需要一个名为 sensitive 的属性(例如,某个 component 的 values 自带一个 sensitive 标志),就必须显式声明外层作用域,与名为 type 或 default 的属性的做法完全相同。下面的显式形式,或在外层作用域上使用 $mode: jsonschema,都可以做到这一点:在 $mode: jsonschema 下,整个节点按编写的 JSON Schema 读取,其中 sensitive 是普通内容,而不是紧凑形式的关键字。
如果 schema 需要以保留关键字命名的属性(例如,带有开发者编写的 description: 字段、type: 字段或 default: 字段的 Component 契约),请对出问题的作用域使用显式形式:
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: false显式形式会绕过分派:properties: 显式列出子项,因此不会产生关键字冲突。
此限制递归地适用于每个推断形式作用域。包含以保留关键字命名的属性的嵌套推断形式对象,会在该作用域被读作约束叶子。修复方法相同:将出问题的作用域改为显式形式。
引用
引用在语法和语义上都借用 JSON Schema 的 $ref::
resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }紧凑格式 schema 中的 $defs: 块用于声明可复用的定义。每个条目本身就是一个紧凑格式(或 JSON Schema,或混合)的 schema。通过 #/$defs/<Name> JSON Pointer 片段进行引用:
将该块声明在引用它的字段所在的数据支柱内部,与这些字段并列,而不是与该支柱并列。schema: 块的顶层只接受三个数据支柱名称,因此写成 values: 同级的 $defs: 会在实体加载时被拒绝,并指出出错的键以及该位置可容纳的支柱集合。无论哪种情况,指针都写作 #/$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" }关于指向 SchemaLibrary 条目的跨文档引用,参见 cross-document-ref.md。关于 OCI URI 简写的展开,参见 uri-grammar.md。
让引用指向定义,而不是属性
指向 $defs: 条目的指针(如 #/$defs/PodResources)是应优先采用的写法。凡是 JSON Schema 允许指针的地方,
指针都是合法的,因此指向已声明属性的指针同样会被接受并强制执行,
但其报告不够精确,在编写之前值得了解其中的差异。
形状来自 $defs: 条目的字段会逐字段检查:失败会在
实际出错的值的路径上报告,并且该字段下的每个失败都会被报告,而不
仅仅是第一个。
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary: resources: { $ref: "#/$defs/PodResources" }此处错误的 cpu 会在 primary.resources.requests.cpu 处报告。
形状来自指向已声明属性的指针的字段,会作为整个文档的一部分 进行检查。约束仍然生效,违反约束的文档仍会中止,但失败 会在携带该指针的字段上报告,而不是在其内部的值上报告;并且当多个 此类字段同时出错时,只会指出其中一个。
primary: resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary: resources: { $ref: "#/properties/primary/properties/resources" }secondary 下错误的 cpu 会在 secondary.resources 处报告。
两种写法接受和拒绝的文档相同,唯一例外是
命名格式中所述的一条关于 format 的限制:通过指针时,形状中位于 anyOf、oneOf 或 not
分支内的 format 不会被检查。除此之外,差异在于消息
能告诉你多少信息,这在编辑器中最为重要,因为标记是根据该路径放置的。同样的情况
也适用于其自身指针又反向指入属性的 $defs: 条目:通过它访问
定义会继承较粗略的报告。
通过 when: 实现条件形状
JSON Schema 2020-12 通过 if/then/else 表达条件形状。紧凑形式提供 when: 作为更直接的简写:一个 Go 模板谓词,若为 true,则应用该节点的其余约束;若为 false,则将该节点视为其约束不存在。
secondary: $ref: "#/$defs/NodePool" when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2 }谓词针对父级的实例值求值。$ 指代外围的对象作用域。当 architecture 为 replication 时,这些约束(required: true,以及额外的 replicaCount: min: 2)叠加在所引用的 NodePool 之上生效。当 architecture 为 standalone 时,这些约束不生效。
谓词可以使用标准 Go 模板函数(Sprig)。编译器将 when: 编译为 JSON Schema 的 if/then/else,并加上一个包装层,在校验运行之前对 Go 模板谓词求值。由于谓词相对于实例是纯的,确定性得以保持。
通过 validate: 和 validateMessage: 进行逐字段自定义校验
有些约束无法用 min / max / pattern / enum 表达。对于这类约束,紧凑形式提供了 validate:——一个 Go 模板谓词,若为 false,则以自定义错误中止校验。
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"该谓词针对字段的值运行(可通过 . 访问);外围对象作用域为 $。若谓词返回 false,校验会使用 validateMessage: 生成错误(若未提供,则使用默认消息)。
validate: 处理 JSON Schema 标准词汇之外的情况:自定义语义校验(semver 格式检查、字符串中的 JSON 内容)、跨字段但作用域较窄的规则(某个字段的约束依赖于同级字段),以及不值得编写完整 assertions: 块的约束。
validate: 与 when: 的作用不同:when: 控制约束是否生效;validate: 本身就是一个约束。
对于作用域较广、真正跨字段的规则,即没有哪个单一字段是“被校验的那个”时,请使用专门的 assertions: 块。参见 templates/assertions-block.md。
将叶子声明为敏感 — sensitive:
values、infra 或 provides 叶子可以声明其所描述的数据携带机密材料:
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 会编译为已解析 JSON Schema 中该节点上的扩展关键字 x-aggrega-sensitive: true,与其他 x-aggrega-* 注解并列。编译器读取它,推导出部署中哪些附件处理已声明为敏感的材料,并将推导出的这一事实携带在编译后的图上。
**在数据本身上声明,而不是在其定位符上声明。**这一区别正是该关键字的全部意义所在,而且很容易弄反。凭据的材料是敏感的;而持有它的资源的名称以及该资源中的数据键并不敏感——两者都是公开的,并且都会以明文渲染到每个引用该资源的消费者中。标记定位符就是对它作出了不实的陈述,并会把这一错误传播到下游所有读取该声明的地方。在上面的示例中,origin 被标记,而 key 刻意没有被标记。
与之互补的陈述——无论什么绑定到这个点,都会处理机密材料,而不管填充对其自身叶子作何声明——根本不是叶子声明。它是附件槽上的 sensitive;参见 entities/component.md “Attachment Slots”。
将整个对象声明为敏感
该关键字可以放在对象上而不是标量上,此时它覆盖该对象之下的所有内容——对象自身的子项,以及更深层嵌套的任何内容。当整个块都是材料,而逐个标记叶子会让别人之后新增的叶子处于未标记状态时,应使用这种声明。
**对象的子项必须放在显式的 properties: 块中。**这是推断对象形式唯一不适用的地方,其原因值得了解,而不是设法绕开:
spec: schema: values: credentials: type: object sensitive: true properties: # required here username: { type: string } password: { type: string }像推断对象形式在其他所有地方允许的那样,把子项直接写在标记旁边,会在编译时被拒绝——第一个子项会被报告为未知关键字,位置指向该子项自身的键:
values: credentials: type: object sensitive: true password: # refused: unknown keyword "password" type: string这种拒绝是正确的,而不是需要绕开的限制。一个节点只要携带紧凑形式关键字,就会被读取为约束叶子,而 sensitive: 正是这样的关键字——因此从那一刻起,每个同级键也都必须是关键字,而 password 不是。properties: 块用来表明“下面的键是属性名,而不是更多关键字”,这与推断与显式对象形式所描述的消歧方式相同。要避免把该诊断误读为“标记不能放在对象上”:它可以,而该块就是表达这一点的方式。
已声明对象内的叶子不需要自己的标记。添加一个标记无害,但也不表达任何新内容,因为对象的声明已经覆盖了它。
该关键字不做什么
这个名称容易引发该关键字并不具备的假设,因此在此明确说明其上限:
- **它不加密任何内容。**它是声明上的注解,而不是保密机制。
- **它不进行验证或拒绝,除非是在填充 CloudFormation 模板参数的地方。**不会因为叶子被声明为敏感而接受或拒绝任何值,也不会改变任何构建结果——唯一的例外是:当 CloudFormation Recipe 或 FeatureRecipe 的
valuesMapping读取已声明为敏感的叶子来填充来源模板的参数时,该映射绑定的每个字面量都会终止构建,因此仅在该声明上不同的两次构建可能会有不同的结局。参见 A secret bound to a CloudFormation parameter would be written into the template(绑定到 CloudFormation 参数的机密将被写入模板)。 - **它不保证渲染输出中不含材料。**制品是否携带材料,取决于作者附加了哪个填充以及作者在其
values中写了什么——参见 architecture/08-credential-model.md “What the compiler does and does not guarantee”。作者内联提供的、已声明为敏感的值,只要构建会渲染它,其渲染方式就与未声明的值完全相同。 - **它不强制使用某种交付机制。**它无法把内联值变成存储引用,也不会收窄槽的
inject允许列表所允许的内容。 - **它不会终止构建,除非是通过上述 CloudFormation 拒绝。**它在构建时发出的通知(见下文)都是建议:构建会运行至完成并写出其制品。是否让通知变为致命,由组织自行选择,以附加到构建的治理策略来表达,而不是该关键字自身会做的事。上述 CloudFormation provider 的拒绝是例外:它会终止构建,因为写入模板的字面量对任何能读取该栈的人都是可读的。
- **在大多数目标上它不会改变任何渲染字节,而且在这些目标上永远不会。**自身带有敏感性概念的目标平台,才是声明有处可落的地方;没有这种概念的目标则永远没有可供它改变的东西。Terraform 是标准库中唯一带有这种原语的目标:当某个 vendored 模块的输入接收作者声明为敏感的材料时,渲染输出会额外生成一个覆盖文件,为该输入声明 Terraform 自身的敏感性属性——参见 providers/terraform.md “Declared-sensitive module inputs”。在其他所有地方,在现有目录中将叶子声明为敏感,所有渲染制品都保持不变。
它会改变工具打印的哪些内容
声明确实会改变的一件事,是工具打印给人阅读的内容:其调试输出,以及拒绝信息的文本(见下文)。在调试界面上,已声明为敏感的值会被替换为固定文本 <redacted>:
aggrega build --trace写入.trace/的逐遍跟踪;aggrega inspect为 Aggregate 打印的逐节点Values:块;aggrega inspect为已解析的 Release 打印的逐叶子附件块。
键始终保留,只替换其值,因此读者仍能看到该叶子是作者编写的,并且有内容被隐去。作者未声明的叶子,即使紧挨着被隐去的同级项,也会原样打印其值——替换只依据声明而不依据其他任何东西,因此名为 password 但没有声明的字段会被打印,而名为 key 的已声明字段则不会。
**声明会覆盖其下的每个叶子,并以相同方式作用于全部三个界面。**当声明位于对象上时,该对象内嵌套的每个值都会被隐去,无论深度如何——对象的声明指名了它们,因此隐去它们并不会声称任何作者未写的内容。匹配基于完整的路径段而不是文本,因此名称仅以某个已声明名称开头的同级项不受影响:声明 dbPassword 不会隐去 dbPasswordHint。
当被隐去的值正是要调试的值时,可以在单次构建中关闭跟踪的隐去:aggrega build --trace --trace-unredacted 会把这些值写入跟踪文件,并在每个这样的文件中加上说明这一点的头部。这是调用时的选择,没有对应的配置项,只作用于跟踪,其文档见 cli/aggrega-build.md “Showing the withheld values”。aggrega inspect 的布局有自己的选项 --unredacted,其文档见 cli/aggrega-inspect.md “Showing the withheld values”。
这一行为的边界比行为本身更重要。
渲染产物从不脱敏。dist/ 下的一切都按渲染结果原样输出,因为它就是可部署物:写入清单的占位符会造成一次损坏的部署,而不是一次受保护的部署。脱敏覆盖的是工具打印的内容,从不覆盖它写入的内容。把声明理解为 dist/ 可以安全发布的承诺,是唯一需要避免的误读——上文所述的上限不变,dist/ 的敏感程度仍等同于其中携带敏感材料最多的那个附件。
声明可能为渲染产物增加一样东西,但那不是脱敏:**当目标拥有自己的敏感性原语时,声明会被渲染到其中。**值仍会被完整写入——没有任何内容被隐去或替换——产物增加的是目标自身在其旁边的标记,使目标的工具能够按作者的声明处理该值。目前提供这种原语的目标是 Terraform,其属性保证什么、不保证什么,见 providers/terraform.md “Declared-sensitive module inputs”。只有当渲染出的名称的身份可以从声明本身恢复时,这种标记才会随之传递;如果名称是模板生成的,标记就会缺失而不会被近似处理,因为标记一个作者未声明的值会对它作出不实的断言。如果该模板是一个 valuesMapping——某个 Recipe 的,或附加到某个组件的 Feature 所对应的 FeatureRecipe 的——构建会对此给出提示,如下文所述。
脱敏覆盖声明所命名的内容,以及模板可见地读取的内容。values 或 infra 支柱中已声明的叶子,以及携带来自已声明敏感的 provides 键的材料的投递键,都按名称识别并被隐去。模板计算出的值落在一个无人声明的键下,因此识别它的依据改为作者写下的引用:在跟踪中,如果 locals: 条目或 source: 字段的模板读取了声明为敏感的叶子,它就会被隐去;读取了已被隐去的同级条目的 locals: 条目同样如此。这种判断有意保守——访问整个对象即访问其下所有已声明的叶子,而把全部数据整体传递出去的模板会访问所有这些叶子——因此无法解析的引用会被隐去,而不是被打印。
**渲染出的文档以重新渲染的形式显示,并注明这一点。**跟踪中解析出的 Workload 是 Recipe 的模板生成的文档:其中没有任何内容记录每个字符来自哪条声明,因此在它内部没有可供替换的键;而逐字段恢复这种关联就意味着检查值的内容——编译器不会这样做。跟踪转而显示的是:同一个 workload: 模板在另一个上下文中再次求值,该上下文里声明为敏感的数据已经读作替换文本,并在文档旁的 workload_note 条目中说明。由于模板在原本是字符串的地方看到的仍是字符串,重新渲染会保持所输出文档的结构,替换文本就位于被隐去数据自身的位置。仍有两处差异,说明中都会指出:依据值的内容进行分支的模板在替换文本下会渲染出不同结果;该维度未命名的数据会原样保留。它是所渲染内容的调试视图,绝不是其副本。
被消费节点的值依据该节点的声明隐去,在边所携带到的两个界面上都是如此。uses 边视图重现目标组件发布的内容,因此由目标自身的 schema 管辖:目标声明为敏感的 provides 键会在消费方的跟踪中被隐去,即使消费方什么都没有声明。如果该边自身的 inject 块将该键路由到消费组件的某个投递键上,该投递键也会被隐去——这与附件的 inject 映射遵循同一规则、读取同一声明,因此两种连线方式不会出现分歧。aggrega inspect 布局显示的是节点自身的支柱及其附件,而不是被消费节点发布的值,因此那里没有需要隐去的跨节点视图。
**写在连接上的附件依据其自身 Feature 的声明隐去,在每个显示它的界面上都是如此。**跟踪在该连接的 uses 边视图下显示它,位于 .context.uses.<alias>.features.<slot>;aggrega inspect 则在已解析 Release 中该连接所在行的下方打印它。在这两处,其 Feature 声明为敏感的 values 或 infra 叶子会被隐去,方式与同一 Feature 直接附加到组件上时完全相同;在跟踪中,Feature 声明为敏感的附件已解析 provides 的键也会被隐去。它的类型、版本、标签以及所有未声明的叶子和 provides 键都原样打印,因此已发布的定位符在其所定位的材料旁仍然可读。在组件或插座上声明 sensitive: true 的插槽,会将附件标记为处理机密材料,但不会自行隐去任何叶子——隐去哪些叶子由 Feature 声明。
机器可读投影按约定原样输出,需要与其来源文件同样对待。aggrega inspect --raw 按作者编写的原样输出实体,aggrega inspect --output yaml 为每种实体(包括 Release)重现作者编写的实体。两者都不做任何替换,这是有意为之:这些输出供脚本解析、供 diff 比较,若输出悄悄隐去自身的一部分,就会错误地呈现它声称重现的输入,并破坏其使用者所依赖的往返一致性。将叶子声明为敏感并不足以使其不出现在这些输出中:请像对待 Aggregate 和 Release 本身一样,对这些输出进行管道传递、存储和共享。
编译图是唯一会隐去值的机器可读投影,无论在何处提供。aggrega inspect、aggrega validate 和 aggrega build 上的 --ir-graph 会把本次运行解析出的图以 JSON 形式写出,与命令原本产生的内容并列;守护进程的 aggrega/irGraph 则以同一张图应答编辑器。在每种情况下,作者声明为敏感的值都会像在可读布局中一样被替换。在 --ir-graph 旁加上 --unredacted 会改为打印这些值,守护进程请求中的 unredacted 字段也是如此。因此,从命令读取的图与通过守护进程协议读取的图是同一份文档,遵循同一处理规则;需要作者原始值的流水线或客户端必须显式请求。
拒绝信息对已声明值的表述
如果一个模板读取了作者声明为敏感的值,由该模板引发的拒绝不会携带该值。当模板中止构建时(调用 fail 的断言、无法求值的表达式、读取结果不是模板必须生成的文档的输出),且其某个引用触及已声明为敏感的数据,所报告的内容来自对同一模板的第二次求值,该次求值所用的上下文中每个已声明为敏感的数据都已读作 <redacted>;除非模板是在它自己完整写出的一句话上中止的,即下面的第一种情况:
assertion failed: the admin password <redacted> must be supplied as a reference- 在模板中完整写出句子的
fail会按原文报告。 如果中止构建的调用是只带一个带引号字符串的fail(即fail "…",没有任何内容通过管道传入,其句子中也没有拼接任何内容),则无论值的内容是什么、无论哪个分支导致了该调用,拒绝信息都会携带这句话,因为这句话没有引用模板读取的任何内容:一个拒绝格式错误的来源的断言会显示它自己对该格式的说明。以其他任何方式构建的句子(printf、字段、变量、通过管道传入fail的值)按后面的情况报告。 - 如果第二次求值在同一表达式上因同一原因失败,报告的就是这次失败。 作者自己写的语句得以保留,原先放值的位置变为
<redacted>;模板编码、加引号或以其他方式转换过的值同样被隐去,因为替换发生在转换之前。 - 如果不是,拒绝信息会指出失败的表达式,并说明其文本已被隐去。 这说明该模板的行为取决于值的内容:面对替换文本时,它走了另一个分支,或在别处失败,因此它组合出的任何内容都不能显示。若要让此类拒绝说明自身原因,请按第一种情况所述,在
fail调用中完整写出其句子。该拒绝仍会中止构建,并保留其代码。 - Workload schema 拒绝渲染出的 Workload 时,其措辞来自 schema。 文档的字段不带有指回其模板所读数据的链接,因此当该模板读取了已声明为敏感的数据时,每条可能引用值的检查结果都改为陈述约束,在值的位置放上
<redacted>,并附上说明原因的提示。不会给出由该值推导出的任何建议;不引用任何值的检查结果(缺少的键、Workload 不接受的键)则照常显示:
.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)- 当流水线步骤的
with输入被该步骤声明的输入契约拒绝时,如果with模板读取了已声明为敏感的数据,其措辞来自契约:列出输入中每个失败的位置和拒绝它的 schema 关键字,随后是说明原因的提示,不包含输入所携带的任何内容。 - 如果某个
source:模板通过读取已声明为敏感的数据生成了一个坐标,那么指出该source:坐标的拒绝,其措辞来自没有任何声明生成的内容:该来源不在锁文件或缓存中、其缓存的归档与锁文件记录的不符,或实体旁记录的固定版本与锁文件不一致。此类拒绝打印的每一行都会指出查找所用的坐标,因此会按 url 以及请求时的版本或引用(在它读取过这些信息的地方)指出来源,其中由此类模板生成的每一项都以<redacted>代替,并说明其原因已被隐去。它保留其代码以及构建为该代码给出的修复建议:
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 produced算作已声明的内容,就是声明所指名的内容,覆盖模板可读取的上下文的每个部分:组件自身的 values 和 infra、附加到该组件及其每个连接上的 Features、携带已声明材料的交付键、其 Component 声明为敏感的 provides 键、上下文所携带的列表中的每个条目(如下文所述),以及由上述任何一项计算得出的 locals: 条目。不读取其中任何一项的模板,其报告与任何地方都没有声明时完全相同,逐字节一致,因此只有读取了已声明值的模板所引发的拒绝才会以不同方式报告。这种读取方式与 trace 所用的相同,依据模板写出的引用:触及整个对象即触及其下每个已声明的叶子,因此它可能隐去并不包含值的文本。一次性传递其全部数据的模板(后面不跟任何内容的点号或 $,传给 toJson 之类的函数、被打印,或交给它按名称调用的模板)会读取其中每个已声明的值,因此其拒绝也以同样方式报告;在 range 或 with 块内,点号是该块迭代或指名的值,传递它只读取该值所含的内容。这里的任何行为都不依赖 --trace-unredacted:该标志只作用于 trace 文件,有无该标志,拒绝信息都相同。
已声明的值无论位于何处都会被隐去,列表之中也不例外。 同一列表中的各条目由不同的实体管辖,每个条目都依据其自身实体的声明被隐去。在边界范围的 FeatureRecipe 所读取的 .boundary 视图中,internal_uses_edges、outgoing_cross_boundary_uses_edges、incoming_cross_boundary_uses_edges 和 cross_boundary_uses_edges 中列出的每个连接都携带其目标所发布的 provides,当目标的 Component 将该键声明为敏感时即被隐去;feature_attachments 的每个条目都携带该附加项的 infra,当其 Feature 声明了该叶子时即被隐去。在附加到组件的 Feature 的上下文中,.context.used_by 的每个条目都携带发起连接的组件所发布的内容,当发起连接的组件所属的 Component 声明了该键时即被隐去。对于其实体未作任何声明的条目,同一个键按原样引用;由被隐去的条目计算得出的 locals: 条目也随之被隐去。遍历列表,或通过 index 访问其中某个条目,都会读取整个列表,因此视为读取了每个条目所携带的内容:
error calling fail: target secret_ref "<redacted>" must start with ref-这一点涵盖构建所引发的拒绝的文本。而告知提供程序其哪些输入来自已声明值的信息——valuesMapping 生成的值、渲染出的 workload: 文档、每个 artifacts: 条目、omits: 条目的每个字段——并不计入从列表内部读取的值,因此提供程序自身对已声明值的处理(包括上文所述 CloudFormation 对绑定字面量的拒绝)不会触及此类值。
有些拒绝不在此范围内。插件写出的文本(provider 或流水线步骤自身的拒绝)是插件的语句,按插件所写原样传递。在构建的断言及其渲染之外求值的模板(Aggregate 中的参数插值和参数检查、schema 的 when: 和 validate: 模板,以及记录其固定版本的 source: 坐标的解析)按其失败的样子报告失败。
以字面量传递的值的构建提示
对于每个以字面量值携带已声明敏感材料的交付键,构建会打印一条提示。当附件的 inject 块把该附件的 Feature 声明为敏感的 provides 键路由到消费组件的某个交付键上,且该值确实被交付时,就会触发:
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 instead关于它,有三点是有意为之的。
它报告的是值如何传递,而不是说明出了问题。 交付字面量往往是目标唯一接受的方式,而且有一整类附件正是为此而存在。该提示告诉作者哪个值走这条路径以及在何处,使这一选择可见而非隐含;它并不声称这一选择是错误的。
它是警告,绝不会中止构建。 构建会成功,并原样写出其产物。希望以字面量交付的凭据导致构建失败的组织,应将其表达为针对构建的治理策略,那才是拒绝该放的地方;某些部署必须打破的规则不应成为编译器的默认行为。
它依据连线来判定,绝不依据值。 该提示读取 schema 声明的敏感性以及作者写出的交付方式。不会检查任何值,因此绝不会根据字段的名称或内容猜测它是凭据,一个碰巧保存了密码的未声明值也不会引发任何提示。
有两种情况有意保持静默。如果交付键所引用的 provides 键没有发布任何内容,就不会交付字面量,也不报告任何内容:该提示只跟随实际发生的交付。而 inject 允许列表为空的槽位把交付交给 Recipe,因此作者没有写出可报告的交付键,也没有需要处理的事项。
该提示自成一类,以其自身的代码为键,--no-unsupported-field-warnings 不会使其静默:该标志涵盖的是目标的保真度提示,那是另一种判断,出于不同的原因被静默。只要语言服务器开启了 --build-on-inspect(或 serve.build_on_inspect 配置键),该提示也会到达编辑器,作为 Aggregate 上的问题显示。为与 aggrega inspect 保持一致,该设置默认关闭:终端命令在检查图时从不进入渲染阶段,因此也不会引发此类提示,而同样不引发提示的编辑器检查,向你显示的就与终端相同。开启该设置就是请求编辑器提供这一额外层,开启时不会向磁盘写入任何内容:该阶段会运行,其产物随即丢弃。它会加入构建在渲染时引发的提示,但不加入任何会使构建中止的检查。每个发布的问题都会指出引发它的层,因此编辑器可以把此提示与解析和分析阶段报告的提示区分开。
针对映射渲染后未带标记的值的构建提示
对于每个声明为敏感的 values 叶节点,如果某次渲染无法携带其标记,而作者仍掌握着对它的控制手段,构建就会为其打印一条提示。该提示在以下渲染时触发:渲染来自某个 source:,且其值是 valuesMapping 的输出——可以是 Recipe 的映射,作用于其 Component 声明的叶节点;也可以是附加到某个组件上的 Feature 的 FeatureRecipe 的映射,作用于该 Feature 声明的叶节点。映射的输出键由映射自行定义,因此没有任何声明指向它们,目标也不会收到该叶节点的逐键标记:
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; ...这一行会按作者编写的坐标指出该叶节点,并指出其映射决定了这一关联的 Recipe 或 FeatureRecipe,因为声明和映射写在两个不同的实体中;附加项的那一行以其附加时使用的名称开头,从而区分同一组件上同一 Feature 的两个附加项。移除映射就是解决手段:没有映射时,source 渲染收到的值以声明的叶节点路径为键,标记会随之传递。仅制品渲染和仅工作负载渲染不会产生提示,因为它们根本不向目标传递值映射;附加到边界上的 Feature 也是如此,它针对空的 values 支柱进行渲染——上述上限在那里是永久性的,警告也指不出任何可做之事。与针对以字面量传递的值的提示一样,它是警告而绝不是中止,不改变任何渲染出的字节,它自成一类,有自己的代码 sensitivity-not-conveyed,且 --no-unsupported-field-warnings 不会使其静默。警告与 Linter 输出给出了它的完整形式。
声明在何处被读取,在何处不被读取
该关键字在它所在的节点上读取,随后读取会沿着声明能够到达该数据的每一条路径进行:嵌套的属性映射、每个组合分支,以及 $ref 的目标。分支和引用目标都会组合到携带它们的属性上,因此通过二者之一找到的声明都归入该属性;只有 properties 下降才会延长路径。
无论标记位于这些关键字旁边,还是位于关键字所到达的内容内部,都会被读取,因此有两种形式无需刻意放置:
- **位于
$ref旁边,或位于引用的目标内部。**引用方叶节点上的标记声明该叶节点。被引用 schema 中的标记同样归入引用方叶节点,路径为该叶节点的路径加上其下方的链——绝不会归入定义内部的路径,那里没有作者编写的值。 - **位于组合关键字(
allOf/anyOf/oneOf)旁边,或位于某个分支自己的properties内部。**分支会组合到携带它的对象上,因此每个分支都会被下降遍历——包括以 JSON Schema 编写的节点的条件分支——其中的声明归入组合属性自身的路径加上其链。
有一种形式确实需要刻意放置标记:
- 放在数组叶节点本身上,而不是其
items元素类型上。元素携带敏感材料的数组要在数组上声明为敏感,因为元素类型不是属性映射,不会被下降遍历。
parameters: 是另一套词汇
sensitive 不属于 parameters: 类型化契约词汇。在参数条目上声明它的 Aggregate 会在该 Aggregate 加载时被拒绝,并产生一条文档封装诊断,报告 unexpected property: "sensitive",定位在出错的键本身——这与该词汇之外的任何键所受的处理相同,因为参数契约是封闭对象。
这种不对称是有意为之:敏感性维度覆盖目录实体声明的三个数据支柱,而参数是环境契约输入,而非支柱叶节点。通过参数提升凭据材料的做法记录在 architecture/08-credential-model.md 的“Legacy charts that demand a formatted string”中,那里说明了这条路径所做的取舍。
使用 allOf、anyOf、oneOf 进行组合
组合关键字的用法与 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 }编译器会在解析后的 JSON Schema 中输出相同的组合关键字。参与组合的每个条目都可以是紧凑形式、JSON Schema 或 $ref: 引用。同一组合内支持混用这几种形式。
逃生舱口 — $jsonschema:
对于超出紧凑形式词汇范围的情况($dynamicRef、unevaluatedProperties、深层 not: 组合、递归类型),任何节点都可以降级为完整的 JSON Schema:
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 }$jsonschema: 块包含 JSON Schema YAML;编译器将其视为透明直通——其内容直接进入解析后 JSON Schema 文档中该节点所在的位置。校验、错误报告和工具都作用于解析后的文档;这种逃逸纯粹是为了方便编写。
not: 分支可以带有一个 description:,说明它所排除的形状为何被拒绝。这样,与该分支匹配的值被拒绝时,会以该描述作为原因,打印在一行上,取代通用的“not allowed here(此处不允许)”措辞——因此应将其写成被拒绝值的作者应当读到的那句话。只有写在 not: 分支本身上的描述才会被使用;写在该分支仅引用的 $defs 条目上的描述不会被使用。
该块内的每个节点都按 JSON Schema 读取,而写在其中的紧凑形式关键字保留其紧凑含义(字符串上的 min: 3 仍是最小长度)。块中的 $ref 与块外的解析方式相同:#/$defs/Foo 指向该支柱 $defs: 中的一个条目,因此示例在那里声明了 Foo;而指向无人声明的条目的引用会在实体加载时被拒绝。$dynamicRef 依据 $dynamicAnchor 解析,因此可以编写递归结构;在递归深处校验失败的值会在持有它的字段处报告——对于一棵 children 条目为 { $dynamicRef: "#node" } 的树,向下两层处错误的 name 会在 tree.children 处报告。
unevaluatedProperties 和 unevaluatedItems 有一项限制。 若写在同时带有引用、组合关键字(allOf、anyOf、oneOf)、条件或依赖 schema 的节点上,二者都会加载但不会被强制执行——并且 unevaluatedItems 在 contains 旁边也不会被强制执行。在上面的示例中,unevaluatedProperties: false 位于 allOf 旁边,因此尽管 Foo 和 patternProperties 都没有声明 extra,{ name: n, extra: 1 } 仍会被接受。
$jsonschema: 逃逸以节点为单位,而不是以文档为单位。一个 schema 可以对简单部分使用紧凑形式,对某个复杂字段使用 JSON Schema 逃逸,对共享结构使用 $ref:——全部在同一个文档中。
在同一文档中混用紧凑形式与 JSON Schema
紧凑形式与 JSON Schema 可以在任意节点边界自由混用。分派规则由内容形态决定:
- 包含
$jsonschema:的节点被视为 JSON Schema(逃生舱口)。 - 包含 JSON Schema 风格顶层关键字(
type:、properties:、additionalProperties:、if:等)的节点被视为 JSON Schema(显式形式)。 - 仅包含“属性名 → 子 schema”条目(没有 JSON Schema 保留关键字)的节点被视为紧凑形式(推断形式)。
- 仅包含
$ref:的节点是引用直通。 - 包含
allOf:/anyOf:/oneOf:的节点是组合;每个条目独立分派。
对于紧凑形式的叶子节点,标准模式是 field_name: { type: ..., constraints... }——一个包含已知紧凑形式词汇的 YAML 映射。分派通过键来识别约束字典。
对于少见的歧义情况(例如,紧凑形式 schema 中有一个字段字面上就叫 type,而推断形式的分派会将其解释为 JSON Schema 关键字),规范的解决办法是使用显式形式——参见上文的“Reserved keywords at every inferred-form scope(每个推断形式作用域中的保留关键字)”。
从文件导入契约 — $import:
契约不必写在声明它的实体内部。$import: 指定一个从中读取契约的文件:
spec: schema: $import: ./contracts/api-server.schema.yaml这样,整个 spec.schema 就来自该文件。该文件的编写方式与它所替换的块完全相同——顶层是各个支柱,其下是紧凑形式或 JSON Schema YAML:
values: greeting: { type: string, enum: [hello, howdy], default: hello }infra: image_tag: { type: string, default: "1.0" }provides: host: { type: string }也可以单独导入某一个支柱,其同级支柱则在旁边内联编写:
spec: schema: values: $import: ./contracts/values.yaml infra: image_tag: { type: string, default: "1.0" }同样的形式也适用于 usesSchema: 插槽的 valueSchema: 和 infraSchema:。
相关规则如下:
$import:是其所在位置上唯一的键。 在它旁边编写的同级键会被拒绝,而不是丢弃两者之一。- 相对路径相对于声明它的实体文件所在的目录解析,而绝不相对于运行构建的目录——与
valuesMapping:、workload:和artifacts:使用的基准相同。路径必须位于该目录之内,因为实体发布时携带的每个文件都取自该目录:跳出该目录的路径或绝对路径所指向的文件不会随实体一起分发,因此会被拒绝——参见 A path names content outside the entity’s own directory(路径指向实体自身目录之外的内容)。多个实体共享的 schema 应放在 SchemaLibrary 中,并通过$ref:引用。 - 导入的文件随实体一起分发。 已发布的实体携带其 schema 导入的每个文件,包括导入链中的每个文件,因此从注册表拉取的副本读取的是同一份契约,并据此校验针对它编写的值——参见
aggrega push。 - 导入的文件承载的是 schema 内容,而不是实体文档。 内容不是 YAML 映射的文件会被拒绝,并给出该文件名。
- 导入的文件本身也可以只是一个
$import:,它会被递归解析;如果导入链回到一个正在读取的文件,则会被拒绝,并给出该导入链。
导入在加载实体时读取,因此读取该实体的每个环节看到的都是同一份契约:aggrega validate、构建、aggrega push、aggrega inspect 以及编辑器。无法读取的文件或不是 schema 的内容会在此时被拒绝,而不会让契约得不到执行——并且 push 会在发布任何内容之前拒绝它。
$import: 与 $ref: 不可互换。$import: 指定一个文件并替换全部内容;$ref: 按标识指定一个 SchemaLibrary 条目,并可在任意节点组合。携带库标识或注册表主机的 $import: 值会被拒绝,并提示改用 $ref:。参见 cross-document-ref.md。
Aggrega 扩展命名空间 — x-aggrega-*
紧凑形式将任何以 x-aggrega- 为前缀的关键字识别为 Aggrega 专用扩展。该命名空间是开放的:新的注解无需逐个关键字修改词汇表即可进入目录。编写 x-aggrega-selector、x-aggrega-narrowed-from 或未来注解的作者,其内容会落在解析后 JSON Schema 中的正确作用域,不会在编译时被拒绝。
命名空间前缀很重要:像 x-agrega-source(少了一个 g)这样的拼写错误不会被识别为扩展关键字,并会被推断形式作用域上的封闭对象语义拒绝。该前缀作用域相当于目录注解层面的拼写错误检测网。
特定的 x-aggrega-* 注解由编译器在流水线中的已知位置生成:
x-aggrega-selector:— 由usesSchema:和featuresSchema:合成过程生成,用于携带指向兼容的提供方 Components 的选择器字符串。x-aggrega-sensitive:— 由声明了sensitive: true的叶子生成。参见上文将叶子声明为敏感。
编写自有扩展关键字的目录作者使用同一命名空间;使用编译后 JSON Schema 的下游工具读取 x-aggrega-* 键时,不会与 JSON Schema 自身的关键字空间冲突。
完整示例 — MariaDB Component schema
下面是一个具有代表性的 MariaDB 数据存储的紧凑形式 Component schema,通篇使用推断形式,并展示了混合的叶子约束、引用、条件结构,以及用于认证块的完整 oneOf 示例:
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 }若用 JSON Schema YAML 编写,同一契约需要为每个对象写出 type: object、properties: 和 additionalProperties: false,并在父级的 required: 中再次列出每个必填字段,因此篇幅会长得多。在更大的 Component 契约中,紧凑带来的收益会不断累积,其意义足以让紧凑形式成为 schema:、parameters: 和 SchemaLibrary 条目的默认编写方式。
交叉引用
- 关于跨文档
$ref:解析语义(跨文档引用旁的required:语法;库到库的链式展开;使用方收窄库):cross-document-ref.md。 - 关于
assertions:块的编写语法(紧凑形式的validate:无法表达的跨字段规则):templates/assertions-block.md。 - 关于承载紧凑形式 schema 的数据支柱集合(
values:、infra:、provides:、uses:、features:、locals:、parameters:):data-pillars.md。 - 关于 OCI URI 简写的展开规则(域名默认值、注册表段、版本回退、发布者展开):uri-grammar.md。
- 关于 SchemaLibrary 实体的编写(可通过
$ref:引用的 schema 在目录中的存放位置):../entities/schemalibrary.md。