Is there a way to define mutually exclusive properties in OpenAPI v3+?

Viewed 252

I am trying to work out if there is a concise way to describe my API using OpenAPI v3+, where I have a response object containing multiple properties, of which some are mutually exclusive and required.

For example, suppose I have an API that always returns an 'id' but then depending upon the type of resource will always additionally return one and only one other property (e.g. 'apple' or 'orange' but never both).

In similar questions around query parameters, I have seen solutions involving usage of min/maxProperties and oneOf (e.g. How to define mutually exclusive query parameters in Swagger (OpenAPI)?). However I don't believe I can use min/maxProperties, because that could lead two mutually exclusive objects being returned, and the use of oneOf seems verbose as you end up specifying the same properties multiple times as per this example (which I think works but seems awkward):

    schema:
      type: object
      oneOf:
        - require: [id, apples]
          properties:
            id:
              type: integer
              example: 123
            apples:
              type: string
              example: test
        - require: [id, oranges]
          properties:
            id:
              type: integer
              example: 123
            oranges:
              type: string
              example: test

Am I missing an obvious solution or is this the only way of doing this?

0 Answers
Related