Examples of oneOf keyword are incorrect

[adambordas]

The documentation that describes the oneOf keyword has wrong examples in it.

The specification looks like this:

  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

There are three examples:

1. The following JSON object is valid against one of the schemas, so the response body is correct:

{
  "bark": true,
  "breed": "Dingo" 
}

Correction: The JSON object is valid for NOT ONLY one of the schemas. It indeed has the two properties of Dog, but it is also valid aginst Cat, as Cat has no required properties defined AND it also allows additionalProperties. (additionalProperties defaults to true according to https://swagger.io/specification/). So the validation will fail.

2. The following JSON object is not valid against both schemas, so the response body is incorrect:

{
  "bark": true,
  "hunts": true
}

Correction: The JSON object is VALID against both schemas because neither Dog nor Cat defines required properties and both allow additional properties by default. So the validation will fail.

3. The following JSON object is valid against both schemas, so the response body is incorrect – it should be valid against only one of the schemas, since we are using the oneOf keyword.

{
  "bark": true,
  "hunts": true,
  "breed": "Husky",
  "age": 3 		
}

Correction: The statement above is true, but the example is misleading. It is not valid for both schemas because it contains both schemas' properties. It is valid against both schemas because both Dog and Cat allow additional properties by default.

[moxley]

Hi @slapers, you are correct. The Cat and Dog schemas need required properties in order for the oneOf schema to work properly.

#279 (comment)

[iglosiggio]

Hi, this was recently reported to OpenAPI asking for clarification (OAI/OpenAPI-Specification#3477). Does this project accept PRs?

[vm-001]

This had been confusing me... I don't see this repo containing that page, so I assume the community is not able to correct that.

[zorba128]

See somehow related #348