Recommended

oas2-oneOf

Formats:

Severity:

Polymorphism is a concept that exists in JSON Schema. OpenAPI is a superset of JSON Schema which means it can inherit (or abandon) what ever it likes.

oneOf is a keyword that was not introduced into OpenAPI until version 3.0.

It’s a common mistake when working on specifications, reading newer docs and mixing and matching capabilities. This rule checks for those mistakes.

We would recommend against using ‘oneOf’ in general. It might make things easier to build complex models, but it does not translate well when tools like code generators try and create polymorphic structures, and the target language doesn’t support inheritance; (like golang).

Think of it this way: As a consumer of this API, ‘oneOf’ means my application is getting a number of different types of objects back. My application would have to build logic to cater to each different variation of response combinations.

It could be meat, could be cake, it could be meat-cake!.

It’s not a great DX.

Make your API definitions explicit in nature.

Why did this violation appear?

The specification is a swagger specification (OpenAPI 2). vacuum found references to oneOf in the specification, that should not be there.

Bad example

swagger: 2.0
paths:
 /mystery:
  post:
    parameters:
      - in: body
        name: whatCouldItBe
        schema:
          oneOf:
            - $ref: "#/shared-components/schemas/Meat"
            - $ref: "#/shared-components/schemas/Cake" 
          ...

Good Example

openapi: 3.1
/pets:
  post:
    requestBody:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/shared-components/schemas/Meat"
              - $ref: "#/shared-components/schemas/Cake"

How do I fix this violation?

Don’t use oneOf with a Swagger/OpenAPI 2 spec. It’s not compatible.

Spectral Equivalent

The rule is equivalent to oas2-oneOf