Cross-dependency of attributes in OpenAPI 3.0

Question

I need to define swagger/OpenAPI v 3.0 file for a search API. My request can specify either geospatial coordinates (longitude and latitude) or (postal code and country code) or (city and state and country code). Beside these I do have couple more mandatory attributes, like distance and distanceUnits.

I know how to do it in JSON schema

            "dependencies": {
                "postalCode": ["countryCode"],
                "city": ["state", "countryCode"],
                "longitude": ["latitude"],
                "latitude": ["longitude"]
            },
            "anyOf": [
                {
                    "required": ["longitude", "latitude"]
                },
                {
                    "required": ["postalCode", "countryCode"]
                },
                {
                    "required": ["city", "state", "countryCode"]
                }
            ]
        }

but I have troubles defining it in swagger. OpenAPI 3.0 allows oneOf and anyOf constructs, but if I am trying to use it in required section, swagger editor gives me an error.

Any help will be greatly appreciated.

score 0 · Accepted Answer · answered Sep 13 '21 at 18:24

To define oneOf/anyOf logic for request parameters, you would have to define all parameters as a single object-type parameter, as explained here.

parameters:
  - in: query
    name: params  # This name will NOT appear in the request URL
                  # but will be used in generated client SDKs / server stubs
    required: true

    # serialize this object as ?key1=value1&key2=value2
    style: form
    explode: true

    schema:
      type: object
      properties:
        longitude: { ... }
        latitude:  { ... }
        postalCode:  { ... }
        countryCode: { ... }
        city:  { ... }
        state: { ... }
      anyOf:
        - required: [longitude, latitude]
        - required: [postalCode, countryCode]
        - required: [city, state, countryCode]

Note that OpenAPI 3.0 does not support the dependencies keyword of JSON Schema, but it's supported in OpenAPI 3.1 (the latest version).

There's also an existing feature request in the OpenAPI Specification repository to support dependencies between individual parameter definitions.

Thank you. However, is OpenAPI 3.1 published? I did not find it on https://swagger.io/resources/open-api/ page — Gary Greenberg, Sep 13 '21 at 19:44
OAS 3.1 was published in February 2021 - https://spec.openapis.org/oas/v3.1.0.html. But currently there's almost no tooling support for it. — Helen, Sep 14 '21 at 06:46

Cross-dependency of attributes in OpenAPI 3.0

1 Answers1