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

Question

虽然我看过OpenAPI规范中的例子：

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

我不明白为什么使用additionalProperties是地图/字典的正确模式。

规范中关于addtionalProperties的唯一具体内容是：

以下属性取自JSON模式定义，但它们的定义已根据Swagger规范进行了调整。它们的定义与JSON模式中的定义相同，只有在原始定义引用JSON模式定义的情况下，才会使用模式对象定义。

• 项目
• allOf
• 属性
• 附加属性

Answer 1

首先，我找到了一个更好的解释addtionalProperties：

对于对象，如果给定了该名称，除了properties中定义的属性外，还允许使用所有其他属性名称。它们的值必须与此处给出的模式对象相匹配。如果未给出，则除了属性中定义的属性外，不允许使用其他属性。

我终于明白了这一点：

使用属性，我们可以定义一组类似于Python的命名元组的已知属性，但是如果我们希望有更像Python的判决，或者任何其他哈希/映射，我们不能指定有多少个键，也不能预先指定它们是什么，我们应该使用addtionalProperties。

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

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

Answer 2

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

一些可能有用的进一步背景：

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

JSON模式使用properties关键字验证预先已知的名称-值对；并使用附加属性（或模式属性，OpenAPI 2.0不支持）验证未知属性。

为清楚起见：

• 属性名或映射中的键必须是字符串，不能是数字或任何其他值。
• 如你所说，属性名应该是唯一的。不幸的是，JSON规范并没有严格要求唯一性，但是唯一性是推荐的，也是大多数JSON实现所期望的。这里有更多的背景。
• 属性和addtionalProperties可以单独使用，也可以组合使用。当addtionalProperties单独使用时，没有属性，对象基本上起到map的作用