Swagger UI's display of multiple-typed attributes is confusing

[thanatos]

Q&A (please complete the following information)

• OS: OS X
• Browser: Firefox Developer Edition
• Version: 63.0b14
• Method of installation: dist assets
• Swagger-UI version: 3.19.3
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: '3.0.0'
info:
  title: Foo API
  version: '0.1.0'
components:
  schemas:
    FooType:
      type: ['null', 'string', 'number']

(The important part is the JSON Schema type field being a list.

Swagger-UI configuration options:
We use the defaults in the dist assets, except we set validatorUrl to null.

Describe the bug you're encountering

The output is confusing. This is how the above JSONSchema will be rendered by Swagger UI:

Some whitespace between the different possible types, perhaps a , , or some indication that it must be one of those types, would greatly clarify what is happening.

[hkosova]

OpenAPI does not support type as an array of types. JSON Schema supports this, but OpenAPI does not, and if you paste your example into the Swagger Editor it will report syntax errors.

The correct way to define multi-type OpenAPI schemas is oneOf or anyOf, with an extra nullable: true for nullable types.

components:
  schemas:
    FooType:
      oneOf:
        - type: string
        - type: number
      nullable: true

Check out the Data Types guide.

[thanatos]

I can't generally paste schema into the Swagger Editor, due to it being hosted on a third party site, among other issues.

I suppose there's nothing actionable here, then, since I was under the apparently false impression that OpenAPI was incorporating JSONSchema for validation.

This is a more broad complaint, but it would be extremely helpful if Swagger UI itself validated OpenAPI schema it were presented with, and presented the user with actionable error messages. (Its usual response to a malformed schema is to crash, which makes debugging nigh impossible.)

[shockey]

@thanatos:

I suppose there's nothing actionable here, then, since I was under the apparently false impression that OpenAPI was incorporating JSONSchema for validation.

OpenAPI does incorporate JSON Schema, but there are limits, which the specification covers in detail (emphasis mine):

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schema-object

---

it would be extremely helpful if Swagger UI itself validated OpenAPI

Thanks for the feedback 😄

We've made the decision to keep validation in Swagger Editor, since the UI is commonly used by folks that can't edit the document (think of a company using Swagger UI to host their documentation... if I'm using their API and there's a bug in their document, why should I get a validation error about it?), while the Editor is almost always used by someone that has the power to fix any errors that crop up.

[creichert]

It's clear that OpenAPI has diverged from JSON Schema. What's not clear is why this compromise was made? Can you point me to an issue that points out why?

From an external tooling providers perspective, this makes is difficult to use standard JSON Schema tools with OpenAPI.

[shockey]

@creichert - that's a great question for the OpenAPI Technical Development Committee (which I'm not a part of).

The OpenAPI issue tracker is a good place to start - here's a historical discussion concerning the JSON Schema constraints in Swagger/OpenAPI 2.0: OAI/OpenAPI-Specification#333. Also, OAI/OpenAPI-Specification#1263.

You may be interested in reading through the alternativeSchemas proposal: OAI/OpenAPI-Specification#1532

[shockey]

Closing due to inactivity.

This is simply to keep our issue tracker clean - feel free to comment if there are any further thoughts or concerns, and we'll be happy to reopen this issue.