Examples of oneOf keyword are incorrect

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.

Start from the documentation page that describes the oneOf keyword and compare its three JSON examples with the OpenAPI specification, especially the defaults for required properties and additionalProperties. Done means the examples and explanations accurately show when oneOf validation succeeds or fails.