jsonopenapianyof

Cross-dependency of attributes in OpenAPI 3.0


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.


Solution

  • 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.