Make it clear that `additionalProperties` can only have a schema value

JSON Schema allows for additionalProperties both a boolean or an object value. true is interpreted as “additional properties follow no restrictions”, false means “no additional restrictions”, and an object is interpreted as a JSON schema applied to the property values (the empty object is thus equivalent to true).

The Schema object description says:

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI 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

This would be naively interpreted as additionalProperties can have a boolean or a schema value (with a schema being interpreted as an OpenAPI schema, not a JSON schema).

In Swagger-Codegen #1318, @webron commented that this was actually meant as “the value of additionalProperties can only be a (Swagger) Schema object”, not a boolean.

Some more discussion was in #477 here.

(I just hit an API which used booleans in several places, and fails with swagger-codegen.)

To make this clearer in the next version of the spec, I suggest to add the following sentence to the cited paragraph above (before the list):

Alternative values of other types (boolean) are not allowed.

I’m not totally happy with this wording, feel free to propose a better one. Maybe we should instead simply redefine additionalProperties generally?

[ePaul]

I guess we could instead write the new definitions of those four fields explicitly:

The following properties have similar, but still slightly different definitions as in the JSON schema specification:

Field Name	Type	Description
items	Schema Object	For arrays, this defines a schema which has to match all of the elements of the array.
allOf	[ Schema Object ]	If this is given, all of the given schemas need to match a value for this schema to match the value (in addition to other properties directly in this schema).
properties	Properties Object	For an object, this defines which properties (and with what kind of values) are allowed in the object.
additionalProperties	Schema Object	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.

(The definition of items is how I – and I guess everyone I’ve met – have interpreted it until now … the definition in JSON schema strangely doesn’t say anything about that the array elements actually have to match the schemas.)

In addition, we would need this section about a properties object:

Properties Object

The properties object defines which properties (both names and values) are allowed in an object.

Patterned fields

Field Name	Type	Description
.*	Schema Object	This allows a property with the given name. Its values must match the given schema object.

[webron]

3.0 now supports boolean values as well for additionalProperties - introduced by #894.