Swagger API Docs XOR

Question

I'm wondering if it's possible, to use an XOR in a swagger.yaml/json If I have something like this for example:

PostableEntity:
  properties:
    first_property:
      type: string
    second_property:
      type: string
      minLength: 1
      description: foo
    third_property:
      type: number
  required:
    - third_property

Now how can I make first_property required if second_property is not set and the other way around?

Answer 1

Conditional properties cannot be modeled, but you might go for a workaround using polymorphism. You could create a parent model P with third_property and two child models (C1 and C2), one (C1) with first_property the other one (C2) with second_property. Using the allOf keyword and a discriminator field, you'll get either a model with properties form P+C1 or P+C2.

See chapter Composition and Inheritance (Polymorphism) in the documentation.

Swagger allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes in an array of object definitions that are validated independently but together compose a single object.

HINT:

Don't get confused when your swagger editor reports you the following error using the allOf keyword: No additional properties allowed, but property <foo> is set

There is currently a bug that is already reported on github, see this link.