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

[ePaul]

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?

[dehora]

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 is confusing spec language. In particular the last sentence is too hard to follow - the definitions can't be the same and not be the same. Also there don't seem to be any local definitions defined - the link in the statement "the Schema Object definition is used instead." points back to this section.

What seems to be happening here operationally, is that four properties from JSON Schema are being changed in Open API while keeping the property names.

This seems to indicate what's going on, in more direct language

The following property names are taken from JSON Schema specification but their definitions
are changed in Open API to disallow boolean values - only an object value representing a JSON schema applied to the property values is allowed.

• items
• allOf
• properties
• additionalProperties

[ePaul]

@dehora I think the point of the original language was to replace all places in a schema where a nested "JSON Schema object" occurs (this is just inside of those four properties, and in some which are not supported at all) with a "Swagger Schema object".

So Swagger model schemas (or now OpenAPI model schemas) work similar to JSON schemas, with some restrictions (e.g. anyOf, oneOf, not, additionalItems, patternProperties are not allowed) and extensions (readOnly, externalDocs, xml, x-* are allowed in addition). Those restrictions and extensions also apply to any nested schema objects in items, allOf, properties and additionalProperties.

Your proposed wording removes this point, because now any JSON schema objects can be nested, even ones which are not legal OpenAPI model schemas. (Also, the value of properties is an objects, only those property values again are schemas. The value of allOf is an array of schemas.)

(I think that boolean values were forbidden is just a side effect, which might have been intended, but was not explicitly written out.)

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

[ralfhandl]

@ePaul The definition of how items is to be interpreted for validating array items is hidden in section 8.2. Array Elements of the JSON Schema specification, quite some distance from the definition of ìtems itself. I knew I had read it somewhere, and still it was hard to find again.

[ePaul]

@ralfhandl Nicely hidden, thanks for finding. I guess the guiding point here is section 4.4:

4.4. Validation of container instances

Keywords with the possibility to validate container instances (arrays or objects) only validate the instances themselves and not their children (array items or object properties). Some of these keywords do, however, contain information which is necessary for calculating which schema(s) a child must be valid against. The algorithms to calculate a child instance's relevant schema(s) are explained in a separate section.

It should be noted that while an array element will only have to validate against one schema, object member values may have to validate against more than one schema.

Strange way of saying this. I think JSON schema needs some rewording as well, but this is out-of-scope for this discussion.

[webron]

Thanks @ePaul. We could have definitely done better work with the 2.0 wording, but that's in the past.

I suggest we keep this ticket open but it may be affected by #333.

Parent: #589.

[webron]

Tackling PR: #741

[boillodmanuel]

Hello,

I wonder how to tell that a definition does not support additional properties. It didn't figure out with a schema?

[handrews]

Note that in the forthcoming-very-soon-now draft-wright-01 (a.k.a. Draft 06), any schema or subschema, not just "additionalProperties" and "additionalItems", can be a boolean:

true is {}
false is {"not": {}}

This both allows for a more clear expression of intent on behalf of schema authors and allows implementations to optimize these cases- true always passes validation, false always fails, no instance check needed. It also means that the "additional*" keywords are no longer special cases- handling their boolean values is like handling any other boolean values.

The confusing language and section organization about "container instances" has also been reworked btw.

[webron]

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