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.

Helen · Accepted Answer · 2021-09-13 18:24:31Z

0

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.

answered Sep 13, 2021 at 18:24

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Gary Greenberg Over a year ago

Thank you. However, is OpenAPI 3.1 published? I did not find it on swagger.io/resources/open-api page

Helen Over a year ago

OAS 3.1 was published in February 2021 - spec.openapis.org/oas/v3.1.0.html. But currently there's almost no tooling support for it.

Collectives™ on Stack Overflow

Cross-dependency of attributes in OpenAPI 3.0

1 Answer 1

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related