55

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

2 Answers 2

54

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.
4
  • 2
    Epstien, although your answer is correct, I am not sure if it addresses the question I was struggling with: How come additionalProperty maps (pun not intended) to a dictionary or map. Also if my answer is mostly correct, it is somewhat incorrect, and I didn't understand from your answer what is incorrect in it.
    – Chen Levy
    Dec 20, 2016 at 13:03
  • Chen, thanks for the comments. I updated my answer with more details that I hope will be helpful to you and other readers. The focus of my answer was to provide some further background and insight, not to correct your answer. Hopfully my 3rd bullet point, taken in context, answers your original question (though not necessarily better than your own answer). Dec 20, 2016 at 13:35
  • 1
    Chen, there were only a couple of points in your answer that might not be 100% correct, and I tried to address those in my answer. (1) Where your answer says "keys (their names or number)", that seems to suggest that properties can use number values as keys. In fact, the names have to be strings. (2) Where you said "additionalProperties will match any property name," Maybe obvious, but I thought I should point out that it won't match property names included under the properties keyword. Dec 20, 2016 at 13:44
  • Ted, thanks for that comment. When I wrote "their names or number" I meant to say "the names of the keys or how many keys there are", I fixed my answer to avoid this confusion.
    – Chen Levy
    Dec 20, 2016 at 16:23
51

First thing, I found a better explanation for additionalProperties:

For an object, if this is given, in addition to the properties defined in properties all other property names are allowed. Their values must each match the schema object given here. If this is not given, no other properties than those defined in properties are allowed.

So here is how I finally understood this:

Using properties, we can define a known set of properties similar to Python's namedtuple, however if we wish to have something more like Python's dict, or any other hash/map where we can't specify how many keys there are nor what they are in advance, we should use additionalProperties.

additionalProperties will match any property name (that will act as the dict's key, and the $ref or type will be the schema of the dict's value, and since there should not be more than one properties with the same name for every given object, we will get the enforcement of unique keys.

Note that unlike Python's dict that accepts any immutable value as a key, since the keys here are in essence property names, they must be strings. (Thanks Ted Epstein for that clarification). This limitation can be tracked down to pair := string : value in the json specification.

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.