Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Question

Although I have seen the examples in the OpenAPI spec:

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

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

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

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.

• items
• allOf
• properties
• additionalProperties

Answer 1

Chen, I think your answer is correct.

Some further background that might be helpful:

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 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.

For clarity:

• 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.