OpenAPI空数组/对象查询参数序列化及相关规范问询

基于OpenAPI 3.1规范的allowEmptyValue选项，目前已有大量关于空字符串序列化的讨论，但未查询到关于查询参数中空数组、无必填属性的空对象的处理说明。

假设存在以下参数定义：

paths:
  "/test":
    get:
      parameters:
      - name: possiblyEmptyArray
        style: form
        in: query
        explode: true
        required: true
        schema:
          type: array
          items:
            type: number
      - name: possiblyEmptyObject
        style: form
        in: query
        explode: true
        required: true
        schema:
          type: object
          properties:
            a:
              type: number
            b:
              type: string
            c:
              type: boolean

仅从JSON格式的Schema规则来看，空数组/空对象是合规的：

• possiblyEmptyArray：[] 和 [1,2,3] 均合法
• possiblyEmptyObject：{}、{"a": 1}、{"a": 1, "b": "hi"} 及 {"a": 1, "b": "hi", "c": true} 均合法

但在查询参数序列化场景下，不同explode配置会产生不同的问题：

• 当explode: true时，空数组/空对象会生成空查询字符串（即参数完全不出现）
• 当explode: false时，会生成类似?possiblyEmptyArray=、?possiblyEmptyObject=的形式（=后无内容）

问题与解答 #

1. 启用explode的必填数组/对象查询参数，空数组/空对象是否合规（为空时不显示在查询字符串中）？
   从OpenAPI 3.1规范的字面定义来看，required: true仅要求参数必须存在有效值，而空数组/空对象本身是Schema允许的有效值。但explode: true的序列化规则中，空数组/空对象确实不会生成任何查询参数键值对——这就产生了矛盾：参数逻辑上是必填且合法，但序列化后完全消失。
   实际场景中，这种情况通常被视为不合规，因为服务端可能会因为查询参数缺失而返回400错误。建议要么修改Schema，限制数组/对象不能为空（比如给数组加minItems: 1，给对象加minProperties: 1），要么在序列化时强制保留参数名（比如切换为explode: false的形式）。

2. 未启用explode的查询参数，空数组/空对象的情况是否合规？正确的序列化方式是什么？
   这种情况是合规的。根据OpenAPI 3.1的form样式序列化规则，当explode: false时，空数组/空对象应序列化为参数名=的形式（即=后无内容）。服务端可以通过这种形式识别到参数存在且值为空，符合required: true的要求。
   注意：部分工具可能会对这种形式有不同处理，但从规范角度来说，?possiblyEmptyArray=和?possiblyEmptyObject=是正确的序列化结果。

3. allowEmptyValue选项对此是否有影响？
   allowEmptyValue的设计初衷是允许将空字符串作为参数值传递，它主要针对的是**原始类型（如string、number）**的空值场景，对数组/对象类型的空值处理没有明确的规范关联。由于OpenAPI文档明确不推荐使用该选项，建议不要依赖它来解决空数组/空对象的序列化问题，而是通过Schema约束或序列化配置来处理。

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