"value property should match exactly one schema in oneOf" message with right example

[GillesTourreau]

I have the following YAML example which I edit on the Stoplight Studio (Windows version)

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
            examples:
              'Cat example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  hunts: true
                  age: 15
              'Dog example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  bark: true
                  breed: Dingo
      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

Two errors are displayed at the line 19 and 23 which explain that the examples are invalid and does not match the Dog or Cat schemas.
Can you confirm that it is a bug of the Stoplight studio validator ?

[philsturgeon]

I've moved this over to the spectral repository, which is the validator powering this functionality in Studio.

[P0lip]

Hey @GillesTourreau!
Thanks a lot for filing the issue.
The behavior described is valid.
Let me explain why.

oneOf compound keyword enforces a single match of the schema from the array.
To illustrate it, let's take the following schema as an example.

{
  "oneOf": [
     { "type": "number" },
     { "type": "integer" }
  ]
}

Now, 2.2 value would be considered valid, because it's a number, but it's not an integer.
However 2 would be treated as invalid, because it's both a number and an integer.

On the other hand, anyOf would be satisfied, since it's a "one or more" kind of scenario.

(using anyOf is one of the way of resolving the issue in the document.)

fixed doc (option 1)

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
            examples:
              'Cat example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  hunts: true
                  age: 15
              'Dog example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  bark: true
                  breed: Dingo
      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

Now, one may ask why both schemas are actually matched.
Both of them look slightly different, after all.
The thing here is that they lack required or additionalProperties.
JSON Schema is relatively relaxed, and simplifying things a bit, relies on keywords to perform the validation.

Let's extract one of the schemas.

type: object
properties:
  bark:
    type: boolean
  breed:
    type: string
    enum: [Dingo, Husky, Retriever, Shepherd]

Now, if you provide such a schema to any validator, these are, more or less, the steps it'll perform.

• verify the type of the data -> must be object

  2 // fails the validation, it's not an object

• alright, it's an object. Let's take the next keyword properties and iterate over the values in it.

• • if bark is present, verify the type of bark -> must be boolean

     { "bark": 2 } // invalid! it's not a boolean

• • if breed is present, verify the type of breed

    { "breed": 2 } // invalid! it's not a string

• • • verify breed against the enum values

      { "breed": "York" } // invalid, incorrect breed!

This means, that as long as all these steps pass, the value is considered value.
If you take a closer look, you can see that if you don't provide a property, it'll pass through just fine.

{
  "foo": {} // this is valid!
}

To change it, you can either leverage additionalProperties and set its value to false, to instrument the validator you don't expect other properties other than the ones you authored under properties.
Alternatively, you can use required to demand the presence of a given property.

fixed doc option 2

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
            examples:
              'Cat example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  hunts: true
                  age: 15
              'Dog example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  bark: true
                  breed: Dingo
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
      additionalProperties: false
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer
      additionalProperties: false

fixed doc option 3

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
            examples:
              'Cat example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  hunts: true
                  age: 15
              'Dog example':
                value:    # <--- "`value` property should match exactly one schema in oneOf" error display.
                  bark: true
                  breed: Dingo
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
      required: [bark, breed]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer
      required: [hunts, age]

oneOf can remain in such a case, as one of the values will be invalid.

Does that make sense?