关于OpenAPI Callback规范与示例结构差异的技术问询

1. onData 的本质 #

onData 是回调场景的自定义名称，属于OpenAPI规范中Callback Object的顶层键。规范允许在callbacks下定义多个命名的回调项，每个名称对应一类回调逻辑（比如数据推送回调、状态变更回调），用来区分不同的回调触发场景，这是规范明确支持的设计，并非示例额外添加的层级。

2. 插值URL的来源 #

{$request.query.callbackUrl}/data 是使用OpenAPI 运行时表达式生成的动态回调路径：

• {$request.query.callbackUrl} 表示从原始请求的query参数中提取客户端预先指定的回调基础URL；
• 拼接/data后，构成最终的回调目标路径，这种设计是为了支持客户端自定义回调地址的常见场景，完全符合规范中对动态路径模板的定义。

3. 规范与示例的结构差异误解 #

你之前对规范结构的理解存在偏差：

规范定义中，Operation Object下的callbacks属性为Callback Object，其直接子项为[pattern]对应的Path Item Object

实际上，Callback Object本身是一个键值对集合：

• 顶层键是回调的自定义名称（如onData）；
• 每个键对应的值才是包含[pattern]路径模板的结构，即层级为：callbacks → 回调名称 → 路径模板 → HTTP操作（get/post等）。
  官方示例完全符合这个规范结构，不存在层级差异。

4. 关于修正方向的说明 #

不需要调整示例或规范，因为示例是严格遵循规范编写的，问题根源是对Callback Object的结构定义理解有误。

内容的提问来源于stack exchange，提问作者Balázs Édes