Openapi-specification: Clarify spec about schemas with multiple types

[ePaul]

In #1401 of swagger-core, @webron mentioned that specifying multiple types for a schema is not valid.

The 2.0 Spec says for a schema object:

The following properties are taken directly from the JSON Schema definition and follow the same specifications:
[...]

• type

JSON Schema validation says in section 5.5.2:

5.5.2. type

5.5.2.1. Valid values

The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.

String values MUST be one of the seven primitive types defined by the core specification.

5.5.2.2. Conditions for successful validation

An instance matches successfully if its primitive type is one of the types defined by keyword. Recall: "number" includes "integer".

I would interpret this as my type: ["integer", "string"] property being valid JSON Schema, and thus also valid Swagger.

While the "null" type name is not available in swagger due to it missing in the list of available types, the same consideration applies to something like "type": ["integer", "string"]. If this is not supposed to be valid, the sentence quoted above needs to be changed.

(Also, instead of referring to the "latest" version of JSON schema, I would explicitly name the version used, so the validity of Swagger documents doesn't suddenly change whenever there is a new version of JSON schema.)

Related issues I found here: #297, #229, #403.

[webron]

@ePaul - thanks for opening the ticket. Where do you see a reference to the "latest" version of JSON Schema?

[ePaul]

@webron ah, seems I was wrong here ... it explicitly says "draft 4". There is a "latest" in the URL used to link to it in the Datatypes section, though this is likely caused by the JSON schema website not providing any URL for the individual versions.

[webron]

Okay, thanks for the clarification.

Sorry about for the confusion about the type, I'll get it clarified in the next few days.

[webron]

Not sure if we'll update 2.0 to reflect that clarity, but we will add the clarification to 3.0 assuming it stays the same.

Parent: #589

[webron]

Tackling PR: #741

[webron]

This has been clarified in #894.

[TedDriggs]

@webron is there a separate issue requesting support for this, or is this the correct issue and OpenAPI's stance is that it won't be supported?

[darrelmiller]

@TedDriggs It will not be supported in V3.0. Whether support will be added in some future version depends on community feedback.

[TedDriggs]

Whether support will be added in some future version depends on community feedback.

What's the preferred channel for that feedback? (this is something my team would benefit from, so I'd like to +1 an issue if one exists, and make sure I'm subscribed to any discussion on the issue)

[webron]

Not sure if there's an existing ticket or not, would suggest searching the repo. Given the added support for oneOf, the need to support direct multi-types seems lower, but feedback is welcome.

[RoyHP]

+1 for supporting array of types according to JSON Schema, we need this. I understand there's a disclaimer indicating that JSON Schema is not entirely supported, but if you're supporting the type key in the first place, it really ought to behave in the same manner.