How to define in swagger spec either of two properties are not null and required

Question

I have a requirement to have two properties in the payload say property1 and propert2. Both are array type. Condition is, that either both can have values, or only one of them will be non-null. But both cannot be null at the same time. How can I define this requirement in swagger spec, so that I can enforce schema such that both should not be null but any one of them can be null.

Valid Examples:

Ex1--> {"Property1": ["value1"], "Property2": ["value2"]}  
Ex2--> {"Property2": ["value2"]} 
Ex3--> {"Property1": ["value1"]}

Invalid Example:

{"Property1": [], "Property2": []}

By "null" do you mean "property is either not included in the payload, or its value is an empty array"? Empty arrays and omitted properties are not the same as the property having the `null` value. — Helen, May 13 '22 at 13:51
Yes by null I meant property either not included or array being empty. Sorry about the confusion with incorrect words. — Pankaj Chouhan, May 15 '22 at 02:10

score 2 · Accepted Answer · answered May 15 '22 at 10:34

Assuming the object can only contain these two properties (Property1 and/or Property2) and no other properties, your use case can be defined using a combination of object-level minProperties and array-level minItems:

MyObject:
  type: object
  minProperties: 1  # <-- requires at least one of Property1 or Property2 to be present
  properties:
    Property1:
      type: array
      items:
        type: string
      minItems: 1   # <-----
    Property2:
      type: array
      items:
        type: string
      minItems: 1   # <-----

If the payload can also contain other properties, the "either Property1 or Property2 must be present" condition can be defined using anyOf + required. This requires OpenAPI 3.x:

# openapi: 3.x.x

MyObject:
  type: object
  anyOf:   # <----------------
    - required: [Property1]
    - required: [Property2]
  properties:
    Property1:
      type: array
      items:
        type: string
      minItems: 1
    Property2:
      type: array
      items:
        type: string
      minItems: 1
    SomeOtherProperty:
      ...

How to define in swagger spec either of two properties are not null and required

1 Answers1

Linked