跨文档 `$ref:` 解析
本页说明 Aggrega 的 schema 编写层面中跨文档 $ref: 引用的解析语义——即当 $ref: 跨越文档边界进入某个库时,Components、Features 和 SchemaLibrary 条目的作者所看到的行为,以及按语法划分的 required: 规则,这些规则确定了哪些编写形式能与跨文档展开顺畅配合。
$ref: 原生遵循 JSON Schema 2020-12。它出现在 schema: 内容中(Component、Feature、SchemaLibrary 条目)、紧凑形式的 schema 中,以及 usesSchema: 和 featuresSchema: 生成的合成 JSON Schema 层中。本页重点介绍跨文档的情形,即 $ref: 指向位于单独文件或 OCI 制品中的 SchemaLibrary 条目。
关于目录实体继承(Component 扩展 Component),参见 inheritance-and-interface.md。一个 Release 扩展另一个 Release 是另一种机制,作用于不被目录索引的文档;其说明见 entities/release.md。
$import: 是另一个能够访问文档外部内容的关键字,两者解决的是不同的问题。$ref: 按标识引用某个 SchemaLibrary 中的条目——由目录解析,由锁文件提供版本——并且可以在任意节点进行组合。$import: 引用实体旁的文件,并用该文件的内容替换整体内容。$import: 既适用于 schema 层面,也适用于 valuesMapping:、workload:、artifacts: 和 parameters:;关于在 schema 上使用 $import:,参见 compact-form-authoring.md §“Importing a contract from a file”。
$ref: 解析语义
$ref: 遵循 JSON Schema 2020-12 的标准解析方式。实践中会出现以下几种引用形式:
- 同一文档内的本地片段:
{ $ref: "#/$defs/PodResources" }—— 解析为该 schema 的$defs下的PodResources条目。 - 按标识引用的 SchemaLibrary 条目引用:
{ $ref: "WebPrimitives#/schemas/URL" }—— 即裸名称形式<Library>#/schemas/<Entry>。库名称在已解析的目录中解析,#/schemas/<Entry>这一 JSON Pointer 片段选择具体条目;版本由 lockfile 提供,而不是由引用提供。引用不携带注册表主机——带主机的oci://<host>/…形式会在编译时被拒绝,并给出引导作者改用标识形式的诊断,因此物理注册表位置永远不会进入编写的源码。库的字节从何处提供(本地目录、内容缓存或远程注册表)由解析器负责,在解析时绑定,绝不属于引用的一部分。 - 文件路径不是引用目标:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }会在 schema 编译时被拒绝,诊断会指出应使用<Library>#/schemas/<Entry>形式。保存在实体旁文件中的 schema 内容应改用$import:引入,它与实体读取的所有文件一样,受限于实体自身的目录。
引用在编译时解析。展开器将被引用的内容内联到使用方的 schema 中;渲染出的 IR 携带的是内联后的内容,而不是间接引用。
$ref: 可以自然地与 JSON Schema 的组合关键字组合使用:
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."allOf 将被引用的 NodePool 结构与附加约束组合在一起。
跨文档 $ref: 下的 required: 语法
目录作者在 Component 或 Feature 上声明必需属性时,可在两种编写形式之间选择:叶级标记(在每个属性上写 required: true)或父级数组(在对象作用域写 required: [name1, name2, ...])。这两种形式在 JSON Schema 2020-12 中都有效,并且只要按本节所示的位置编写,在跨文档 $ref: 展开下两者都会生效。
不含 $ref: 的推断形式编写:叶级标记在编译时累积。编译器遍历每个属性,若某个叶节点带有 required: true,就将该属性名加入合成父节点的 required: 数组。
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }编译器在父级作用域输出 required: [database, display_name]。
带有 $ref: 的使用方——在跨文档 $ref: 旁边只能写 properties、required 和 description,使用方添加的必填项就是它在那里写的那些:父级的 required: 数组,或在其于 properties: 下声明的属性上写的叶级 required: true 标记。被引用条目自身的必填项——其推断形式中的叶级标记,或它自己的 required: 数组——会通过引用原样生效。父级数组只需列出必填项,无需重新声明条目已声明的属性:
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]在使用方于引用旁声明的属性上,叶级标记同样有效——因此在那里写 properties: { database: { type: string, required: true } },会使 database 成为必填,效果与 required: [database] 完全相同。使用方的属性会替换条目中同名的属性(参见使用方收窄库条目),因此请按你想要的结构重新声明它。
库到库的链式展开
一个 SchemaLibrary 条目本身可以包含指向另一个 SchemaLibrary 条目的 $ref:,从而形成一条链。编译器在编译时遍历这条链:展开某个条目时遇到的每个 $ref: 本身也会被展开,并按持有它的库的语境进行解析。
# Library Aspec: schemas: DatabasePayload: type: object properties: host: { type: string } credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)spec: schemas: BasicAuth: type: object properties: username: { type: string } password: { type: string }引用 DatabasePayload 的使用方 Component 会得到完全展开的结构,其中 credentials 由库 B 的 BasicAuth 填充。违反该链所贡献约束的值,会在被检查文档中该值自身的路径处被拒绝,且拒绝信息不会指明该约束来自哪个库条目;请从使用方沿 $ref: 链查找它。
使用方收窄库条目
使用方 Component 可以声明一个属性,其名称与从库条目引入的某个属性相同。此时,在合并后的结构中,使用方编译后的属性会完全替换库条目的属性。
# Library entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: schema: values: $ref: "Tools#/schemas/ToolContract" properties: side_effects: type: array items: { type: string, enum: [read] } default: [read]在合并后的结构中,side_effects 反映使用方更窄的契约(enum: [read],并带有 default);库条目中更宽的 enum: [read, write, delete] 不再存在。该属性由使用方编写。
这是预期行为:使用方细化库条目的属性是标准的收窄模式。收窄不会留下任何标记:使用方的属性以其自身的来源独立存在。
交叉引用
- 关于目录实体继承(Component-extends-Component、Feature-extends-Feature),参见 inheritance-and-interface.md。
- 关于部署侧文档之间的继承(其引用指向文件而非目录实体):Release 扩展 Release 的说明见
entities/release.md,Manifest 扩展 Manifest 的说明见entities/manifest.md。 - 关于提供方特定的源指针(
Recipe.spec.source.chart:、Recipe.spec.source.modulePath:),请参阅各实体的 Recipe 文档。Provider 源指针并未统一到$ref:之下;由提供方插件直接使用它们。 - 关于 OCI URI 简写的展开规则(域名默认值、上下文相关的实体展开、解析优先级、版本处理),参见 uri-grammar.md。