为什么`additionalProperties`是在Swagger/OpenAPI 2.0中表示Dictionary/Map的方法

Question

虽然我已经看到了OpenAPI规范中的示例:

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

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

这个规范唯一具体的内容additionalProperties也是没有用的:

以下属性取自JSON Schema定义,但其定义已调整为Swagger规范.它们的定义与JSON Schema中的定义相同,只有在原始定义引用JSON模式定义的情况下,才使用模式对象定义.

• 项目
• 所有的
• 性能
• additionalProperties

Answer 1

陈,我觉得你的答案是正确的.

一些可能有用的背景:

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

JSON Schema使用properties关键字来验证事先已知的名称 - 值对; 并使用additionalProperties(或patternProperties在OpenAPI 2.0中不支持)来验证未知的属性.

为清楚起见:

• 地图中的属性名称或"键"必须是字符串.它们不能是数字或任何其他值.
• 如你所说,属性名称应该是唯一的.不幸的是,JSON规范并不严格要求唯一性,但建议使用唯一性,并且大多数JSON实现都需要这种唯一性.更多背景在这里.
• properties并且additionalProperties可以单独使用或组合使用.当单独使用additionalProperties而没有属性时,该对象本质上用作map<string, T>其中T是additionalProperties子模式中描述的类型.也许这有助于回答您的原始问题.
• 在针对单个模式评估对象时,如果属性名称与指定的属性名称匹配properties,则其值仅需要针对为该属性提供的子模式有效.的additionalProperties子模式,如果设置的话,将仅用于验证特性不包含在properties地图.
• additionalProperties在Swagger的核心Java库中实现了一些限制.我在这里记录了这些限制.

Answer 2

首先,我找到了一个更好的解释additionalProperties:

对于一个对象,如果给出了该对象,则除了properties允许在所有其他属性名称中定义的属性之外.它们的值必须与此处给出的模式对象相匹配.如果没有给出,properties则不允许使用除定义之外的其他属性.

所以这就是我最终如何理解这一点:

使用properties,我们可以定义一组类似于Python的namedtuple的已知属性,但是如果我们希望有更像Python的dict,或任何其他散列/映射,我们无法指定它们有多少键,也不能提前它们是什么,我们应该使用additionalProperties.

additionalProperties将匹配任何属性名称(将作为dict的键,并且$ref或type将是该dict值的模式,并且因为每个给定对象不应该有多个具有相同名称的属性,我们将得到强制执行唯一键.

请注意,与Python不同dict,它接受任何不可变值作为键,因为这里的键本质上是属性名,它们必须是字符串.(感谢Ted Epstein的澄清).可以pair := string : value在json规范中跟踪此限制.