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
andadditionalProperties
can be used alone or in combination. When additionalProperties is used alone, without properties, the object essentially functions as amap<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. TheadditionalProperties
sub-schema, if provided, will only be used to validate properties that are not included in theproperties
map. - There are some limitations of
additionalProperties
as implemented in Swagger’s core Java libraries. I’ve documented these limitations here.