AsyncAPI 规范中关于 OpenAPI Schema 属性的处理决策

在 AsyncAPI 规范的实际应用中，开发团队遇到了一个关于 OpenAPI Schema 属性处理的重要技术决策点。本文将深入分析这一技术问题的背景、讨论过程以及最终确定的解决方案。

问题背景

AsyncAPI 规范允许在消息负载(payload)中使用多种模式(schema)格式，包括 AsyncAPI 原生模式(AAS)和 OpenAPI Schema(OAS)。当用户没有明确指定 schemaFormat 时，系统默认将其解释为 AAS 模式。然而，许多用户在实际应用中会使用 OpenAPI Schema 特有的属性，如 example、examples、nullable 和 readOnly 等，这导致了规范验证时的兼容性问题。

技术讨论

在技术讨论中，主要形成了两种观点：

1. 严格验证派：主张当 schemaFormat 未指定时，应严格按照 AAS 规范进行验证，任何 OAS 特有的属性都应被视为验证错误。这种做法的优势是保持规范的严谨性和一致性。

2. 宽松兼容派：考虑到用户实际使用习惯，建议在未指定 schemaFormat 时对 OAS 属性采取更宽容的态度，以提高工具的易用性。

最终决策

经过深入讨论，AsyncAPI 技术团队做出了以下明确决策：

1. 明确格式声明：当用户需要使用 OpenAPI Schema 时，必须显式声明 schemaFormat 为 application/vnd.oai.openapi;version=3.0.0。

2. 严格默认验证：当 schemaFormat 未指定时，系统将严格按照 AAS 规范进行验证，任何 OAS 特有的属性都将导致验证失败。

3. 验证一致性：所有 AsyncAPI 工具链都应遵循这一验证原则，确保跨工具行为的一致性。

技术实现建议

对于工具开发者，建议采用以下实现策略：

1. 在解析消息负载时，首先检查 schemaFormat 属性
2. 根据声明的格式选择相应的模式解析器
3. 未声明时默认使用 AAS 解析器并进行严格验证
4. 提供清晰的错误信息，指导用户正确使用 schemaFormat

总结

这一决策平衡了规范严谨性和用户体验的需求，既保持了 AsyncAPI 规范的完整性，又通过明确的格式声明机制为用户提供了使用其他流行模式格式的途径。对于开发者而言，理解并遵循这一规范将有助于创建更健壮、可互操作的异步API定义。