SchemaLibrary
SchemaLibrary 是一种目录实体,用于存放可复用的 JSON Schema 2020-12 定义以及可选的参数化辅助项。共享相同 schema 结构(URL、时长、通用探针结构、反复出现的资源限制)的 Components 和 Features 只需在库中声明一次这些结构,然后通过规范的 $ref URI 引用它们。该库实体属于第 3 层:需要跨 Component 复用 schema 的目录可以选择启用。没有重复 schema 内容的目录无需包含任何 SchemaLibrary。
SchemaLibrary 的角色
平台架构师编写 SchemaLibraries,用于集中管理在整个目录中反复出现的 schema 结构。库不是可部署的构建块,而是一个定义命名空间。Component / Feature 的作者通过规范的 $ref URI 引用库条目:只需定义一次类型,在引用解析到的每一处都会进行校验。
“库”与“使用方”之间的划分是有意为之。Components 声明实例所填充的契约(其 values、infra 和 provides,其 socket,其凭据槽位)。Features 编码行为附加项。SchemaLibraries 只编码 schema 内容,即值必须满足的结构规则。让这三种角色保持独立,可以使每种实体类型按各自的节奏演进;不需要共享 schema 定义的作者永远不会接触到库实体。
实体信封
SchemaLibrary 实体带有标准的目录信封。apiVersion: aggrega.ai/v1beta1 和 kind: SchemaLibrary 标明实体种类;metadata.name 是一个 PascalCase 标识符;metadata.version 遵循严格的语义化版本。库的内容位于 spec 之下:spec.schemas 为必填项(库必须声明至少一个条目),spec.templates 为可选项(仅当库使用参数化辅助项时才出现)。
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]编写 Schema 条目
Schema 条目以三种形式之一编写。紧凑形式是简短、常见结构的默认写法,适用于 type、pattern、enum、min、max 以及类似的单行约束。JSON Schema 2020-12 YAML 是与之地位相同的编写方式,适用于需要完整 JSON Schema 能力的条目(组合关键字、条件结构、复杂的 $defs)。在单个条目中混用两者是受支持的,由紧凑形式编译器按节点内容结构进行分派;当紧凑形式无法表达意图时,$jsonschema: 逃生舱口可在任意节点嵌入完整的 JSON Schema 内容。
条目中的 format 所做的检查与任何 schema 中的相同:它指定 email、uri、hostname、ipv4、ipv6、uuid、date-time 和 date 之一,消费方为该字段提供的值若不具备该格式则会被拒绝,参见 vocabulary/compact-form-authoring.md。指定任何其他格式(包括 password)的条目会在库加载时被拒绝,因此无论是否已有内容引用它,对整个目录执行的 aggrega validate 都会拒绝它,并指出该库、该条目和该格式名称,同时列出受支持的格式;而其 Release 涉及该库的构建或拉取会因此中止。引用另一个库的条目,在 Component 或 Feature 支柱消费它的位置进行判定。携带机密内容的字段应声明 sensitive: true,而不是声明格式。
模板与 $instantiate:
含有大量重复结构的库在 spec.templates 下声明参数化辅助模板。模板包含一个 $params: 映射(具名且带类型的参数声明)以及一个主体(以 $<paramName> 标量记号引用参数的紧凑形式或 JSON Schema 内容)。Schema 条目通过 $instantiate: + $args: 绑定来实例化模板;替换引擎将参数占位符替换为字面标量值,并生成解析后条目的主体。
spec: schemas: LivenessProbe: $instantiate: ProbeTemplate $args: port: 8080 path: /healthz ReadinessProbe: $instantiate: ProbeTemplate $args: port: 8081 path: /ready templates: ProbeTemplate: $params: port: type: integer path: type: string type: object properties: port: type: integer const: $port path: type: string const: $path替换仅限字面标量。替换引擎不解释 Go 模板语法,不求值条件,也不执行循环。需要表达能力更强的辅助手段的作者,可以组合 Components 或 Features,由它们以各自的变化方式使用库条目。
命名约定
库名称、schema 条目键和模板名称遵循 PascalCase。实体信封的 JSON Schema 通过 pattern 约束在三个位置强制执行该约定:
metadata.name匹配^[A-Z][A-Za-z0-9]*$。spec.schemas的映射键通过propertyNames匹配同一模式。spec.templates的映射键通过propertyNames匹配同一模式。
如果 SchemaLibrary 在 spec.schemas 或 spec.templates 中含有非 PascalCase 的键,则会在工作区加载时无法通过信封校验。信封层面的强制执行承担着关键作用:schema 条目键会出现在规范的 $id URI(#/schemas/<name>)中;模板名称在实例化时引用到规范 URI 中。在加载时捕获非 PascalCase 的键,可以防止它们在目录生态系统中扩散。
模板 $params: 映射中的参数名称仅在模板内部有效——它们不会出现在规范的 $id URI 中,也不在信封层面受 pattern 约束。作者可以采用适合模板参数的任何命名约定;port、path、intervalSec 等小写参数名称较为常见。
库、schema 和模板三个层级命名的统一,使引用标识符清晰易读:WebPrimitives#/schemas/URL 一眼即可看懂。
关于跨文档 $ref: 解析语义——$ref: 如何跨越 SchemaLibrary 边界解析、针对含 $ref: 的使用方的 required: 语法区别、库到库的链式展开,以及使用方收窄库的行为——请参阅 vocabulary/cross-document-ref.md。
引用库条目
Component / Feature 作者通过库条目的标识引用它,即裸名称形式 <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"库名称针对已解析的目录进行解析;#/schemas/<name> 片段选择具体条目。引用不携带注册表主机;作者可以用 <Library>:<version>#/schemas/<name> 声明一个可选的最低版本下限(版本分隔符为 :,与 recipe/feature 映射及 lockfile 锁定一致),但实际解析出的版本由每个 Release 的 lockfile 提供,该 lockfile 按名称 + 版本 + 内容摘要锁定每个被使用的库。携带注册表主机的引用(即 oci://<host>/… 形式)会在编译时被拒绝,并给出一条引导作者改用标识形式的诊断信息,因此物理注册表位置永远不会进入编写的源码。库的字节从何处提供(本地目录、内容缓存或远程注册表)由解析器负责,在解析时绑定;迁移注册表只是解析器配置的变更,而不是源码的变更。
禁用的 JSON Schema 关键字
在 SchemaLibrary 条目中,JSON Schema 2020-12 的 $dynamicAnchor 和 $dynamicRef 关键字被禁用。SchemaLibrary 解析器在工作区加载时扫描 schema 条目和模板主体;发布 linter 在发布时施加一道冗余防护;实例化引擎在参数替换后重新扫描解析后的主体,因此通过参数值夹带禁用关键字的模板依然会失败。这三次扫描共同封堵了静态引入途径(schema 条目或模板主体中的字面量 $dynamicAnchor)、参数化引入途径(包含 $dynamicRef 的 $args: 值),以及借助带外工具绕过的途径(发布时的防护会捕获任何跳过了解析器的内容)。
拒绝触发时,错误会指出违规的关键字和文件路径。作者在编写时即可看到该错误,而不是等到首次实例化时;模板主体不豁免于加载时扫描。
动态引用语义与运行时求值相耦合,这种耦合方式会破坏编译器的编译期确定性契约。需要动态引用行为的作者应重构 schema,改用静态 $ref 解析;该检查不提供豁免。
层级定位
在实体层级文档模型中,SchemaLibrary 属于第 3 层——供需要跨 Component 复用 schema 的目录按需选用。没有重复 schema 内容的目录无需任何 SchemaLibrary 实体即可发布;层级标记表示“高级;不需要可跳过”,用于文档导航,而非表示能力。编译器对 SchemaLibrary 的处理与其他目录实体种类一致:在工作区加载时执行相同的信封校验,对每个条目的内容使用相同的 JSON Schema 2020-12 流水线,在发布时使用相同的 OCI 发布流水线。
在第 3 层内部,spec.templates 参数化辅助机制本身也是按需选用的。具有大量重复结构的库(例如以端口 + 路径为参数的 Probe 模板;以允许的来源为参数的 CORS 模板;以证书 + 密钥路径为参数的 TLS 模板)可以从 templates 复用中获益;条目各不相同、均为一次性条目的库则完全跳过模板块,直接在 spec.schemas 下内联编写每个条目。