Unable to validate when specification having oneOf references

[gurubabujampala]

I'm experimenting with the open API specification using the oneOf keyword. Reference: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

Example API in the specification:

/customers:
    post:
      tags:
        - customer-controller
      operationId: saveCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CustomerAddress'
                - $ref: '#/components/schemas/Customer'
            examples:
              CUSTOMER_ADDRESS:
                summary: Example of a customer address object
                value:
                  id: 1
                  customerId: 1005
                  houseNo: '1234'
                  street: 'B.St'
                  city: 'Melbourne'
                  state: 'Victoria'
                  postCode: '3000'
                  requestType: 'address'
              CUSTOMER:
                summary: Example of a customer object
                value:
                  id: 104
                  customerId: 1004
                  initial: J
                  firstName: John
                  secondName: Doe
                  customerType: GOLD
      responses:
        "200":
          description: OK
          content:
            'application/json':
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CustomerAddress'
                  - $ref: '#/components/schemas/Customer'
              examples:
                CUSTOMER_ADDRESS:
                  summary: Example of a customer address object
                  value:
                    id: 1
                    customerId: 1005
                    houseNo: '1234'
                    street: 'B.St'
                    city: 'Melbourne'
                    state: 'Victoria'
                    postCode: '3000'
                    requestType: 'address'
                CUSTOMER:
                  summary: Example of a customer object
                  value:
                    id: 104
                    customerId: 1004
                    initial: J
                    firstName: John
                    secondName: Doe
                    customerType: GOLD

When I try to execute with specimatic, getting the below error

It appears that Specmatic is prioritizing the initial reference of CustomerAddress and attempting to align all subsequent examples with this reference.

Could you assist me in pinpointing any areas where I might be missing in this situation?

[yogeshnikam671]

Hi @gurubabujampala, thanks for reporting this!
Can you share the schema ref #/components/schemas/Customer with us for further analysis?
Thanks.

[gurubabujampala]

Hi @yogeshnikam671 , it's not the different schema.
As part of POST /customer API request body, it can be expected either of Customer or CustomerAddress components.

Here is the full specification which is having both components schemas.

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: http://localhost:8080
    description: Generated server url
paths:
  /customers:
    post:
      tags:
        - customer-controller
      operationId: saveCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CustomerAddress'
                - $ref: '#/components/schemas/Customer'
            examples:
              CUSTOMER_ADDRESS:
                summary: Example of a customer address object
                value:
                  id: 1
                  customerId: 1005
                  houseNo: '1234'
                  street: 'B.St'
                  city: 'Melbourne'
                  state: 'Victoria'
                  postCode: '3000'
                  requestType: 'address'
              CUSTOMER:
                summary: Example of a customer object
                value:
                  id: 104
                  customerId: 1004
                  initial: J
                  firstName: John
                  secondName: Doe
                  customerType: GOLD
      responses:
        "200":
          description: OK
          content:
            'application/json':
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CustomerAddress'
                  - $ref: '#/components/schemas/Customer'
              examples:
                CUSTOMER_ADDRESS:
                  summary: Example of a customer address object
                  value:
                    id: 1
                    customerId: 1005
                    houseNo: '1234'
                    street: 'B.St'
                    city: 'Melbourne'
                    state: 'Victoria'
                    postCode: '3000'
                    requestType: 'address'
                CUSTOMER:
                  summary: Example of a customer object
                  value:
                    id: 104
                    customerId: 1004
                    initial: J
                    firstName: John
                    secondName: Doe
                    customerType: GOLD
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                  status:
                    type: integer
                  error:
                    type: string
                  path:
                    type: string
                example:
                  timestamp: "2024-04-11T04:50:11.778+00:00"
                  status: 400
                  error: Bad Request
                  path: "/customers"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                  status:
                    type: integer
                  error:
                    type: string
                  path:
                    type: string
                example:
                  timestamp: "2024-04-11T04:50:11.778+00:00"
                  status: 500
                  error: Internal Server Error
                  path: "/customers"
components:
  schemas:
    Customer:
      required:
        - customerType
        - firstName
        - initial
        - secondName
      type: object
      properties:
        id:
          type: integer
          format: int32
        customerId:
          type: integer
          format: int32
        initial:
          type: string
        firstName:
          type: string
        secondName:
          type: string
        customerType:
          type: string
          enum:
            - BRONZE
            - SILVER
            - GOLD
            - PLATINUM
        customerOrders:
          type: array
          items:
            $ref: '#/components/schemas/CustomerOrder'
        verified:
          type: boolean
    CustomerOrder:
      type: object
      properties:
        customerId:
          type: integer
          format: int32
        orderId:
          type: string
        placeDate:
          type: string
        completionDate:
          type: string
    CustomerAddress:
      type: object
      properties:
        id:
          type: integer
          format: int32
        customerId:
          type: integer
          format: int32
        houseNo:
          type: string
        street:
          type: string
        city:
          type: string
        state:
          type: string
        postCode:
          type: string
        requestType:
          type: string

[yogeshnikam671]

Hi @gurubabujampala, thanks for sharing this. I'll get back to you in a while.

[yogeshnikam671]

Hey @gurubabujampala, can I know what Specmatic version you are using? Can you try this once with the latest version which is 1.3.12?
Please let me know if that doesn't get rid of this error.

[gurubabujampala]

Hi @yogeshnikam671 thanks for quick response.
I have tested with the latest version 1.3.12 initially. Upon retesting, it now working fine. Yesterday, during our product discussion, HariKrishnan and I quickly addressed another issue: when a mandatory field, such as firstName, is absent in the request, it produces the same error instead of the expected error message.

[yogeshnikam671]

Hey @gurubabujampala, thanks for reporting this issue with the error messages.
We spent some time looking into it and now have fixed it as part of this PR.
The PR is merged and the issue should be resolved for you with the upcoming release.
Will keep you posted around the same.
cc - @harikrishnan83