EntitySchema

EntitySchema 定义一种业务类型，例如“本机应用”或“前台时段”。它是一个实体，EntityId 叫 SchemaId；它的每个版本是这种类型的一版字段、约束和含义，叫 Schema 版本。

每个业务版本都引用它保存时所用的 Schema 版本。类型后来增减了字段，旧数据仍按当时的 Schema 版本解释，不需要迁移。

本页的规则约束业务类型。Core 类型的结构由 Core 自己定义。

• 类别：Core 类型，category 为 entity_schema
• 被引用：业务版本的 schemaVersionId
• 决策：ADR · 实体模型

字段复制章节链接

字段定义复制章节链接

示例复制章节链接

下面的业务类型有三个字段：title 必须出现，可以为 null；relatedVersionId 是引用；identifiers 是对象数组，每个元素的 sourceVersionId 也是引用。

{
	"displayName": "示例条目",
	"description": "一个带标题、实体引用和平台标识线索的示例条目。",
	"resourceName": "example-items",
	"fields": {
		"title": {
			"type": "string",
			"required": true,
			"nullable": true
		},
		"relatedVersionId": {
			"type": "reference",
			"required": true,
			"nullable": false
		},
		"identifiers": {
			"type": "array",
			"required": true,
			"nullable": false,
			"items": {
				"type": "object",
				"nullable": false,
				"fields": {
					"scheme": {
						"type": "string",
						"required": true,
						"nullable": false
					},
					"value": {
						"type": "string",
						"required": true,
						"nullable": false
					},
					"sourceVersionId": {
						"type": "reference",
						"required": false,
						"nullable": false
					}
				}
			}
		}
	}
}

类型与 Schema 版本复制章节链接

SCHEMA-1 一个 EntitySchema 一种类型复制章节链接

定义

一个 EntitySchema 定义一种业务类型，它的每个版本是这种类型的一个 Schema 版本。同一类型的业务实体共用一个 EntitySchema，各有自己的 EntityId。

SCHEMA-2 按 Schema 版本解释复制章节链接

执行方：后端、读取方

业务版本按它引用的 Schema 版本校验和解释：有哪些字段、哪些位置是引用、每个字段是什么含义，都由这个 Schema 版本决定。

SCHEMA-3 只按声明校验复制章节链接

执行方：后端

后端只按已声明的 EntitySchema 校验业务实体。业务版本引用的 Schema 版本必须已保存。

SCHEMA-4 名称与说明复制章节链接

执行方：写入方、后端

displayName 和 description 必须是非空字符串，后端检查这一点。description 还必须说明这种类型记下的业务事实、粒度和事实时间的取值，由写入方负责，人和 Agent 都靠它理解数据。

资源名与字段名复制章节链接

SCHEMA-5 resourceName 唯一复制章节链接

执行方：后端

resourceName 属于业务类型：同一个 EntitySchema 的各版本使用相同的 resourceName，不同的业务类型不得使用相同的 resourceName。EntitySchema 删除后，它的 resourceName 可以由新的业务类型使用。它用于发现和访问一种类型，用法见 API 和 Storage。

SCHEMA-6 resourceName 格式复制章节链接

执行方：后端

resourceName 只使用小写字母、数字和连字符，并以字母开头，例如 local-applications。

SCHEMA-7 不用 id 字段复制章节链接

执行方：后端

顶层字段不得命名为 id。实体和版本的身份由版本的成员提供。

SCHEMA-8 引用字段的名字复制章节链接

执行方：写入方

reference 字段的名字以 VersionId 结尾，元素是 reference 的数组以 VersionIds 结尾，对象成员也一样。名字的前半部分写目标在这里的角色，例如前台应用时段引用本机应用的 localApplicationVersionId，与 Observation 的 observerVersionId 写法相同。

字段约束复制章节链接

SCHEMA-9 reference复制章节链接

执行方：后端

reference 的非空值必须是 VersionId。顶层字段、对象成员和数组元素都可以是 reference。

SCHEMA-10 三项必写复制章节链接

执行方：后端

每个字段定义必须写明 type、required 和 nullable，三项都没有默认值。数组元素只写 type 和 nullable。

SCHEMA-11 required 与 nullable复制章节链接

执行方：后端

required 和 nullable 分别判断：required 决定字段能否省略，nullable 决定字段出现时能否为 null。

SCHEMA-12 只收已声明字段复制章节链接

执行方：后端

业务实体只接受已声明的字段，对象成员也一样。字段定义只接受字段定义中列出的配置。

SCHEMA-13 省略与 null复制章节链接

执行方：后端

“省略”和“值为 null”是两种状态：省略的字段读回时不出现，值为 null 的字段读回时是 null。

SCHEMA-14 对象与数组复制章节链接

执行方：后端

对象用 fields 声明成员，数组用 items 声明元素；只有 object 有 fields，只有 array 有 items。数组的约束分层生效：

类型的演进复制章节链接

SCHEMA-15 结构变了，出新版本复制章节链接

执行方：写入方

结构或约束改变时，形成同一个 EntitySchema 的新版本。增删字段、调整约束、改写 displayName 或 description 的措辞，都属于这种情况；SchemaId 和 resourceName 保持不变。

SCHEMA-16 含义变了，建新类型复制章节链接

执行方：写入方

业务含义改变时，必须新建一个 EntitySchema，使用新的 SchemaId 和 resourceName。字段改名或改写 description 不得改变旧数据的含义。

SCHEMA-17 旧数据按旧版本读复制章节链接

执行方：后端

新的 Schema 版本只作用于引用它的业务版本。已保存的业务版本继续按它引用的 Schema 版本解释。