为什么`additionalProperties`是在Swagger / OpenAPI 2.0中表示字典/地图的方式

Question

尽管我已经在OpenAPI规范中看到了示例：

 type: object additionalProperties: $ref: '#/definitions/ComplexModel'

对我而言，并不明显的是， 为什么对地图/字典使用additionalProperties是正确的模式。

它也没有帮助，该规范不得不说的唯一具体的东西additionalProperties是：

以下属性取自JSON模式定义，但其定义已根据Swagger规范进行了调整。 它们的定义与JSON Schema中的定义相同，仅当原始定义引用JSON Schema定义时，才使用Schema Object定义。

项目

所有的

属性

其他属性

Answer 1

陈，我认为你的回答是正确的。

一些进一步的背景可能会有所帮助：

在JavaScript（这是JSON的原始上下文）中，对象就像是字符串到值的哈希映射，其中某些值是数据，其他值是函数。 您可以将每个“名称/值”对视为一个属性。 但是JavaScript没有类，因此属性名称不是预定义的，并且每个对象可以具有自己独立的属性集。

JSON Schema使用properties关键字来验证预先已知的名称-值对； 并使用additionalProperties （或patternProperties ，在所述OpenAPI 2.0不支持）来验证是未知的属性。

为了清楚起见：

属性名称或映射中的“键”必须为字符串。 它们不能是数字或任何其他值。
如您所说，属性名称应该是唯一的。 不幸的是，JSON规范并不严格要求唯一性，但是大多数JSON实现都建议并推荐唯一性。 这里有更多背景。
properties和additionalProperties properties可以单独使用或组合使用。 当单独使用extraProperty时，不带属性时，该对象实质上起map<string, T> ，其中T是AdditionalProperties子模式中描述的类型。 也许有助于回答您的原始问题。
在针对单个架构评估对象时，如果属性名称与properties指定的属性名称之一匹配，则其值仅需针对为该属性提供的子模式有效。 所述additionalProperties子模式，如果设置的话，将仅被用于验证未包含在属性properties地图。
有一定的局限性additionalProperties在扬鞭的核心Java库实现。 我已经在这里记录了这些限制。

Answer 2

第一件事，我发现了一个更好的解释additionalProperties ：

对于对象，如果已指定，则除了在属性中定义的properties外，还可以使用所有其他属性名称。 它们的值必须与此处给定的架构对象匹配。 如果未指定，则不允许使用除properties中定义的其他属性。

所以这就是我最终的理解：

使用properties ，我们可以定义一组类似于Python的namedtuple的已知属性，但是，如果我们希望拥有更多类似Python的dict或其他任何我们无法指定键数或键值的哈希/映射，预先，我们应该使用additionalProperties 。

additionalProperties将匹配任何属性名称（将用作dict的键，而$ref或type将是dict的值的模式，并且由于每个属性不应有多个具有相同名称的属性给定对象，我们将强制执行唯一键。

请注意，与Python接受任何不可变值作为键的dict不同，由于此处的键本质上是属性名称，因此它们必须是字符串。 （感谢泰德·爱泼斯坦的澄清）。 此限制可以追溯到json规范中的pair := string : value 。

Answer 3

使用OpenAPI 3.0，以下架构成功返回字典列表：

    MyCustomObject:
      type: array
      items:
        type: object
        properties:
          key: 
            type: string