有两样东西表面上相似,却绝不能被混淆:协议未描述的内容,与协议描述了但值错误的内容。前者是协议成长的方式,后者是缺陷。
规则
未识别内容不是错误。已知值的格式错误是。
- 本实现不认识的类型的事件 MUST NOT 中止运行。
- 事件上未被描述的属性 MUST NOT 中止运行。
- 实现不认识的联合成员——新类型的内容部分、在其发布之后命名的 outcome——MUST NOT 中止运行。
- 协议确实描述、但携带 schema 拒绝的值的字段,MUST 是致命的:消费者 MUST 让运行失败,而不是修复、强制转换或忽略该值。
推理是不对称的,且是刻意的。实现发布之后新增的事件类型是预期之中的——发送方更新,旧一方没有依据称其无效。但 messageId 持有数字不是更新的协议,而是缺陷;悄悄强制转换它的消费者会把缺陷隐藏起来,直到它以更难诊断的形式浮现。
每种传输给出相同答案
这些规则约束协议,而非某种 wire 格式。支持多种传输的消费者 MUST 对同一事件无论以何种方式到达都得出相同结论:若流作为 JSON 存活,它作为 protobuf 也 MUST 存活;若失败,也 MUST 以相同方式失败——除非二进制编码本身无法表达结论所依赖的差异(本页下文列出的两种情形:无法命名的信封变体,以及 protobuf 物化的缺省)。
这限制了读取器可以自行决定的范围。把字节变成事件是读取器的全部职责——字节无法映射到任何事件的帧是解码失败,这个判断属于读取器。成功读取的事件是否携带实现认识的内容,则不属于读取器:这个问题属于所有传输共享的唯一阶段。同时做验证的读取器会让自己的传输比其他传输严格得多,于是生产者对内容类型的选择就决定了运行能否存活。
二进制情形需要一项让步。文本读取器可以把未知类型的事件传下去,因为类型以字符串传输,共享阶段可以按名称丢弃。二进制读取器不能:它未编译对应的信封变体不携带任何可传下去的名称。这样的帧 MUST 被丢弃并警告,而不是让运行失败——这与共享阶段会给出的答案相同,只是为一个无法推迟该问题的传输表述。
二进制编码在它让字段没有存在性的地方无法遵守这一点。protobuf 中这覆盖必填标量与必填列表:生产者省略的必填字符串会以空字符串到达,必填数组以空数组到达,而同样的事件作为 JSON 会因格式错误被拒绝。schema 已禁止省略它们,因此这改变的是缺陷生产者的诊断方式,而非一致生产者可以发送的内容。
消费者如何处理未识别内容
把事件暴露给应用代码的消费者 MUST NOT 把未识别内容当作协议描述过的内容投递。读过之后,此类消费者 MUST 做其一:
- 丢弃,若整个事件都是未识别类型。消费者 SHOULD 发出指明类型的警告。
- 剥离,若是原本有效事件上的未知属性或未识别联合成员。消费者 SHOULD 发出指明被移除路径的警告。
消费者 MUST NOT 让被剥离的属性出现在应用代码收到的值中,也 MUST NOT 让被丢弃的事件到达应用代码。
这只适用于 schema 封闭对象的地方,也就是 schema 描述协议自有对象的每一处。schema 刻意让对象保持开放的地方,其未描述的成员根本不是未识别内容,MUST 被保留。JSON Patch 操作就是这种情形:RFC 6902 第 4 节要求操作忽略未定义成员而非拒绝,因此携带遗留 value 的 remove 是合法 patch,会完整到达。在那里剥离的消费者删除了合规数据,其警告毫无意义。
这约束的是管道,不是解析器。只解析事件的库层——例如各 SDK 的生成模型——会刻意保留未知属性,以便上层中间件仍能看到它们。提供此类解析器但没有执行阶段的 SDK 尚未满足该规则;目前是 Python 与 .NET,其模型宽松解析,没有在应用代码前剥离的阶段。
参考实现尚未满足一种情形:schema 为封闭字符串值集合的字段——例如消息
role——被当作叶子检查,因此未识别的值在那里是致命的,而不是被剥离。.NET 转换器同样拒绝未知 role 或 outcome。上述规则才是协议要求;两者都是对它的缺口,而不是对它的放松。
剥离会一路向下,移除什么取决于无法识别的值所在位置:
- 在可选位置:该字段被移除,周围一切存活。
- 在必填位置:包含它的值被移除。来源类型从未听说过的媒体部分会被整体移除——留下一个没有 source 的部分会交给验证器一个必须视为格式错误的东西,把一次新增变成致命错误。
- 在列表内:无法识别的元素被丢弃,列表存活。
中间件的位置
中间件——消费者安装来翻译、观察或重写流的任何东西——MUST 在执行之前运行,执行 MUST 在验证之前、在应用代码看到任何内容之前运行。
producer → 兼容边界 → 中间件 → 执行
→ chunk 展开 → 验证 → 应用兼容边界是退役形状的常驻翻译器。它 MUST 最先看到流,因为退役形状可能是 chunk;更早遇到它的阶段要么失败,要么把它变成边界无法再识别的东西。中间件链 MAY 在自己的阶段之间展开 chunk,使每个阶段收到 start/content/end 形式——参考实现的链式辅助正是这样做的。
因此中间件 MUST 对两种形式都做好准备:它看到什么取决于它在链中的位置。
阶段之间的展开会收窄一项保证,而这一收窄被明说而非隐藏:展开合成的事件只携带协议定义的内容,因此 chunk 上的未识别字段只有在上述规范顺序下才会存活到执行阶段并得到警告;提前展开的链会静默丢失它们。一致生产者从不发射此类字段,因此丢失的是来自更新协议版本、穿过提前展开链的内容。展开本来要交付的内容——delta、开启字段、metadata、rawEvent、归因——完整传递;chunk 的 timestamp 不会,因为合成事件不是 chunk,且与未知字段一样,只在规范顺序下于展开前被判定。
chunk 本身就是事件,MUST 被当作事件判定:无论哪个阶段先遇到格式错误的 chunk——规范顺序下的执行阶段,或提前展开链中的展开阶段——MUST 拒绝而非修复,且 MUST NOT 规范化、默认或掩盖执行阶段会拒绝的已知值格式错误。
验证 MUST 在展开之后运行,因为它检查的内容——消息与调用在继续前已开启、在之后已关闭——只有在 chunk 变成其所代表的事件后才存在。
顺序在两个方向上都关键:
- 中间件 MUST 在执行移除之前看到内容。shim 存在的意义正是翻译当前协议未描述的形状;若执行先剥离,shim 收到的将是没有内容可翻译的事件,运行会丢失无人能恢复的数据。
- 应用代码 MUST NOT 看到执行阶段会移除的内容。翻译器获得机会后,仍未识别的就是未识别,到此为止。
消费者 MUST 在每条为应用代码产生事件的路径上应用该顺序,包括重连与回放。跳过执行阶段的路径是保证上的漏洞,不是优化。
出站内容
同一边界适用于消费者发送的内容。紧接传输之前,消费者 MUST 从运行输入中移除未识别内容,SHOULD 对移除内容发出警告,并 MUST 在发送前把已知字段的格式错误视为致命。
生产者收到运行输入时 MUST 对其应用同样的不对称性:未识别内容不会使输入无效,已知字段的格式错误会。
生产者不得做的事
生产者 MUST NOT 发射协议未描述的事件类型并期望消费者忽略它。未识别事件存活是为了让协议能新增事件,不是让生产者偷偷把私有信号塞进流里;CUSTOM 与 RAW 正是为此存在,并由 schema 描述。