跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Aggrega Catalog(Component)schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/component-v1beta1.schema.json

原子构建块的抽象定义。

有关编写 Component 实体的文字指导,请参阅 Component 编写参考;本页记录该参考所描述的结构化 schema。

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “Component”是常量:"Component"
metadataobject是
specobject是用于约束开发者不透明 values 载荷的校验与 schema 定义。

不允许其他属性。

component.metadata

属性类型必需描述
namestring是长度至少为 1 个字符。
versionstring是接口的严格语义化版本(例如 1.0.0)。模式:^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。
descriptionstring否说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者为正确选择和使用它所需了解的内容——它对部署它的 Release 有什么期望,以及它的行为中任何出人意料之处。通常写一个简短的段落即可。
maintainersobject[]否拥有此实体的维护者列表。
licensestring否此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。
repositorystring否源文件所在 Git 仓库的 URL。
homestring否此实体的主页、wiki 或文档的 URL。
keywordsstring[]否用于提升 UI 可发现性的描述性关键字列表。
labelsobject是用于声明特征的鸭子类型标签。必须包含保留键 ‘component.aggrega.ai/type’。
annotationsmap of string否由 Platform Architect 在 Domain 2 中编写的、不可变的组件固有特征。向下级联到 .context.annotations.catalog 存储桶。

不允许其他属性。

component.metadata.maintainers[]
属性类型必需描述
namestring是
emailstring否
urlstring否

不允许其他属性。

component.metadata.labels

用于声明特征的鸭子类型标签。必须包含保留键 ‘component.aggrega.ai/type’。

属性类型必需描述
component.aggrega.ai/typestring(枚举)是保留的分类轴,指明该组件属于哪一类事物。Aggrega 定义了此键及其可接受的值,因此该集合是封闭的;若要按你自己的轴对组件分类,请在此键旁添加你自己的标签键。允许的值:"server"、"worker"、"task"、"function"、"stateful-server"、"resource"

component.spec

用于约束开发者不透明 values 载荷的校验与 schema 定义。

属性类型必需描述
extendsstring否该 Component 所扩展的基础 Component 的 URI。扩展组合的是结构:基础的 metadata 标签与注解、其挂载槽(featuresSchema)、其自注入允许列表(inject)以及其拓扑插槽(usesSchema)均被继承,该 Component 可以在其上添加,或逐键替换继承的条目。基础的数据支柱不会被组合——基础的 schema 块按基础编写的原样继承,因此扩展的 Component 写作 schema: inherited,且不编写任何自己的支柱内容。
featuresSchemamap of object否声明式挂载槽定义:该实体期望挂载 Feature 的具名绑定点。槽约束哪些填充可以绑定它(selector)以及填充的材料如何交付(inject);填充自身的 Feature 拥有其 values 和 infra 契约。声明槽从不会封闭挂载块——作者可以用任何槽都未声明的名称挂载 Feature,因此同一个实体既可服务于槽填充的挂载,也可服务于在更大范围共享的凭据。槽是绑定点,而不是依赖插槽:usesSchema 声明的是独立的拓扑面。
injectstring[]否允许列表中的自注入交付机制(例如 [‘env’, ‘file’, ‘arg’])。存在时,开发者可在 Aggregate 中组件级别使用 inject: 块,将自己的 values 或 provides 键直接注入交付管道。若省略,则禁止组件级自注入(黑盒模式——由 Recipe 处理所有内部连线)。语义与 usesSchema[].inject 相同,但约束的是组件自身的 values,而非跨组件拓扑。可以列出除 all 以外的任何机制名称;任何 inject 块都不能使用 all 这个名称。
usesSchemamap of object否该实体声明的依赖插座,以插座名称为键;通过某个插座建立的每个连接都会对照该插座的声明进行检查——其选择器、它允许的 inject 机制以及其逐连接契约。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。
schemaany否涵盖自由形态支柱的 JSON Schema 2020-12 内容:values(Developer 的领域——Developer 在 Aggregate 中为每个 Component 实例配置的应用形态参数);infra(Operator 的领域——由 Release 提供的物理规格调节项);以及 provides(该 Component 通过拓扑管道向消费者公开的下游上下文键)。通过内容形态分派接受四种编写模式:(1) 内联内容(承载紧凑形式、JSON Schema YAML 或混合形式的 YAML map);(2) 通过 {$import: } 进行文件替换,写在 spec.schema 处以从一个文件提供整个契约,或写在单个支柱处以仅提供该支柱,相对路径相对于声明它的实体所在目录读取;(3) 通过 {$ref: #/schemas/} 以裸名称标识跨文档引用 SchemaLibrary 条目(版本由每个 Release 的锁文件提供;引用中不出现注册表主机);(4) 裸字符串 inherited,这是声明了 extends 的 Component 唯一可写的形式——它表明三个支柱按基础 Component 编写的原样来自基础。模式 1 至 3 编写内容,仅适用于未声明 extends 的 Component;模式 4 不编写内容,且每个声明了 extends 的 Component 都必须使用。配套字段 usesSchema 和 featuresSchema 涵盖固定形态的支柱(依赖插槽、挂载槽);编译器将这三者组合为用于校验实例的单一 schema。
assertionsmap of string否构建时的跨字段校验。每个条目都是一个命名断言:键是一个稳定的规则标识符,会在错误消息中显示;值是一个 Go 模板字符串,具有 {{ fail "message" }} 的中止语义。每个实体的多个命名断言按作者声明的顺序逐实例求值;第一个失败的断言会中止构建。Component 断言在解析和静态分析之后、渲染之前求值,表达的是契约的架构不变量,无论绑定的是哪个 Recipe 都成立。模板上下文:.values / .infra / .uses / .features / .metadata。求值器使用 missingkey=error:引用未定义的键会以 no-such-key 诊断中止。由于裸引用在任何回退执行之前就会中止,在此处普通的 default 无法为可选字段提供回退——请用 hasKey 保护该引用,或使用 optional 辅助函数,它会直接执行存在性检查。通过 index 读取该键同样无法提供回退:index 在映射中不存在该键时会中止,并给出该键的名称。继承是累加的:声明了 extends 的 Component 会同时按其继承的断言和自身的断言求值,继承的规则在前;任意深度的继承链从链根向下累积——因此当不止一条规则会失败时,报告的是在链中声明位置最靠上的那条。复用继承来的名称来声明不同的规则,会在针对目录解析 extends 链时被拒绝,并给出两个 Components 的名称以及共用的名称——因此该错误在基础 Component 存在时才会出现,而不会仅凭扩展文档本身出现;扩展的 Component 只能添加规则,绝不能替换规则。在同一名称下逐字节重述继承的规则是允许的,它本身就是一个空操作。不会检查两条规则能否同时成立:互相无法同时满足的一对规则属于编写错误,它会在某个实例触发先生效的那条时表现为普通的断言失败,而绝不会预先给出警告。

不允许其他属性。

定义

extending-component-must-declare-schema-inherited

在存在 spec.extends 时适用。扩展型 Component 会原样获得其基础 Component 所编写的 values / infra / provides,因此它声明 spec.schema: inherited,且不编写任何支柱内容。另外两种情况都是错误,而且是不同的错误:完全省略 spec.schema,这会让读者无法区分继承而来的支柱块与被遗忘的支柱块;以及在 spec.schema 下编写支柱内容,这相当于在一个契约本就来自其基础的 Component 上要求第二份、相互分歧的契约。

属性类型必需描述
schemaconst “inherited”是继承标记,也是声明了 extends 的 Component 上 spec.schema 唯一可取的值。它指明支柱的来源;支柱内容本身属于基础 Component。常量:"inherited"

non-extending-component-authors-its-own-schema

在不存在 spec.extends 时适用。不扩展任何基础的 Component 在 spec.schema 下编写自己的 values / infra / provides 内容,因此该字段承载的是编写的内容,而非继承标记:该标记表示支柱来自某个基础,而此 Component 没有基础。

属性类型必需描述
schemaobject否编写的支柱内容——一个映射,采用 spec.schema 所记述的三种内容编写模式中的任意一种。