为什么`additionalProperties`是在Swagger / OpenAPI 2.0中表示Dictionary / Map的方式 [英] Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

问题描述

虽然我已经看到 OpenAPI中的示例规格：

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

对我而言很明显为什么使用 additionalProperties 是地图/字典的正确架构。

it isn't obvious to me why the use of additionalProperties is the correct schema for a Map/Dictionary.

它也没有帮助，规范对 additionalProperties 的唯一具体事项是：

It also doesn't help that the only concrete thing that the spec has to say about additionalProperties is:

以下属性取自JSON模式定义，但其定义已调整为Swagger规范。它们的定义与JSON Schema中的定义相同，只有原始定义引用了JSON Schema定义，才使用Schema Object定义。

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification. Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the Schema Object definition is used instead.

• 项目


• allOf


• 属性


• additionalProperties




• items
• allOf
• properties
• additionalProperties




推荐答案

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

可能有用的其他背景：

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

In JavaScript, which was the original context for JSON, an object is like a hash map of strings to values, where some values are data, others are functions. You can think of each name-value pair as a property. But JavaScript doesn't have classes, so the property names are not predefined, and each object can have its own independent set of properties.

JSON Schema使用 properties 关键字来验证提前知道的名称 - 值对;并且使用 additionalProperties （或 patternProperties ，OpenAPI 2.0不支持）来验证不知道的属性。

JSON Schema uses the properties keyword to validate name-value pairs that are known in advance; and uses additionalProperties (or patternProperties, not supported in OpenAPI 2.0) to validate properties that are not known.

为了清楚起见：



• 地图中的属性名称或键必须是弦。它们不能是数字或任何其他值。


• 如你所说，属性名称​​应该是唯一的。不幸的是，JSON规范并不是严格要求唯一性，而是建议使用唯一性，大多数JSON实现都是预期的。更多背景此处。 <>
  
• 属性和 additionalProperties 可以单独使用或组合使用。当附加属性单独使用时，没有属性，对象基本上作为一个映射< string，T> 其中T是additionalProperties子模式中描述的类型。


• 根据单个模式评估对象时，如果属性名称与属性，它的值只需要针对该属性提供的子模式有效。 additionalProperties 子模式（如果提供）将仅用于验证属性中包含的 / code> map。


• 在Swagger的核心Java库中实现的 additionalProperties 有一些限制。我已经记录了这些限制 here 。


• The property names, or "keys" in the map, must be strings. They cannot be numbers, or any other value.
• As you said, the property names should be unique. Unfortunately the JSON spec doesn't strictly require uniqueness, but uniqueness is recommended, and expected by most JSON implementations. More background here.
• properties and additionalProperties can be used alone or in combination. When additionalProperties is used alone, without properties, the object essentially functions as a map<string, T> where T is the type described in the additionalProperties sub-schema. Maybe that helps to answer your original question.
• When evaluating an object against a single schema, if a property name matches one of those specified in properties, its value only needs to be valid against the sub-schema provided for that property. The additionalProperties sub-schema, if provided, will only be used to validate properties that are not included in the properties map.
• There are some limitations of additionalProperties as implemented in Swagger's core Java libraries. I've documented these limitations here.

这篇关于为什么`additionalProperties`是在Swagger / OpenAPI 2.0中表示Dictionary / Map的方式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！