openapi - Mutually excluding properties in swagger

Question

How do I indicate that in my_object you can have property_1 or property_2, but not both?

my_object:
  type: object
  properties:
    property_1:
      type: string
    property_2:
      type: string

Answer 1

In OpenAPI 3.0 (openapi: 3.0.0), you can use the oneOf keyword to define mutually exclusive conditions. This schema requires that either property_1 or property_2 be present, but not both:

my_object:
  type: object
  properties:
    property_1:
      type: string
    property_2:
      type: string
    property_3:
      type: string
  oneOf:
    - required: [property_1]
    - required: [property_2]

If at least one of these two properties must be present, use anyOf instead.

Note: While oneOf is part of the OpenAPI Specification (as in, you can write API definitions that include oneOf), actual tooling support for oneOf may vary and be limited.

If you use OpenAPI 2.0 (swagger: "2.0"), it does not support oneOf, so you can only document this condition verbally in the schema description or property descriptions.