Support interdependencies between query parameters

[cwarny]

It would be great to be able to specify interdependencies between query parameters. In my app, some query parameters become "required" only when some other query parameter is present. And when conditionally required parameters are missing when the conditions are met, the API fails. Of course I can have the API reply back that some required parameter is missing, but it would be great to have that built into Swagger.

[webron]

This is something that's very complicated to describe elegantly. Feel free to suggest a format that you think would be suitable for it.

[cwarny]

My suggestion would be as follows: instead of having the field "required" boolean, make it either boolean or an array of references to other parameters. If you put required: true, it would have to always be present. If you put required: [$a, $b], it means that this parameter is required only when parameters a and b are present.

[mohsen1]

How you describe an endpoint where one of it's parameters is required if another query parameter is equal to a string or is larger than a number? This can get very complicated. I would say if a parameter is required sometimes it's not required.

[cwarny]

I'd say either keep it simple and only allow simple interdependencies like, if a is present, then bis required (i.e. required: [$a, $b]), or define simple operations like, required: [$a>3, $b=="hello", "world" in $c]. I would favor keeping it simple, but then I have to admit that my only response to "why not keep it even simpler (i.e. as it is now) and only have a boolean required" is: it's a matter of how useful more sophistications are. For me, having simple interdependencies is useful and better than just a boolean required, but I don't think I need more complicated stuff. Other people might disagree.

[webron]

While this may be a solution, it can also be a validation nightmare. Definitely not something that can be done with a json schema.

[iisurge]

maybe something like
"required": false, "depends": [ $a, $b ]

[rcork]

Don't forget the "OR" dependency. I have a service where one of two query parameters must be present but it doesn't matter which one. For now we are just documenting the interdependency and using a error schema with the appropriate code/message but would be preferable to have this defined in the contract up front.

[fractalawareness]

+1 for cwarny simple suggestions

[filipnowakswissre]

My use-case is to have only one property of the parameter required, but from the array of the definitions.

[craig-bayley]

You can solve the OR use case already using an enumerated filter_type paired with a filter_value query parameter(s).

Example:

        - name: filter_type
          in: query
          description: What type of values to filter on
          required: false
          type: string
          enum: [location, service, name]
          default: location
        - name: filter_value
          in: query
          description: The value to apply to the filter_type. Should match what was in the filter, i.e. if filtering on location use a location name.
          required: false
          type: string
          default: all

[filipnowakswissre]

wow, good one, thanks

[ePaul]

@craig-bayley could you format your example as YAML, please? Just adding

```yaml
[...]
```

around it makes it much easier to read.

[craig-bayley]

@ePaul Thanks for the tip. Done.

[scottmas]

+1 Something like this would be very nice.

[fehguy]

Folks just to set expectations, we're not doing this in the initial cut of 3.0

[handrews]

some query parameters become "required" only when some other query parameter is present

The JSON Schema "dependencies" keyword does exactly this. The "if"/"then"/"else" keywords (json-schema-org/json-schema-spec#180) that seem likely to go into a near-future draft would also accomplish this (probably more clearly for most people).

[webron]

I don't see how JSON Schema would be relevant for this at all.

[handrews]

@webron further up you said:

Definitely not something that can be done with a json schema.

so I assumed that meant that JSON Schema was at least potentially relevant, which meant that I should point out that JSON Schema can in fact do this. I think you were specifically referring to an approach based on "required" which would not be valid JSON Schema, but there is JSON Schema support for this use case.

[webron]

Gotcha. That referred to the validation of it, not the representation of it in the spec. I assumed you were referring to the representation, making it my bad.

[k11k2]

When it going to be on air ? much needed one.

[jainpradeep100]

I have need to generate @context HttpHeader parameter by Swagger. Is it possible or not? If possible then how it would be accomplish.

[webron]

@jainpradeep100 for tool-specific questions, please ask in its respective support channel, not here.

[AML14]

I just opened an issue in the OpenAPI Generator repository: OpenAPITools/openapi-generator#8722

It is a feature request, which we are willing to start developing, but would like to get as much feedback from the community as possible. The point is: Based on the IDL dependencies included in OAS, we could automatically generate built-in assertions in the source code of clients and servers (any programming language) that handle the validation of such dependencies.

I think this was one of the main ideas when this issue was opened, but it's going to be big, so we need to discuss it all together and provide our own views on the matter.

[SteveNay-vz]

This issue is now over 6 years old. :-( OAS 3.1 was just released yesterday. I don't want to do any disservice to the IDL solution offered by @AML14, but was anything done to support inter-parameter dependencies in v3.1?

I'm not overly familiar with JSON schema (now fully supported in 3.1), but I spent a little time reading about dependencies and "applying subschemas conditionally" (if/then/else), and I don't see how they can help with inter-parameter dependencies. Unless I missed something, both of those concepts only apply within an object, but query parameters are completely separate objects, each with their own schema.

If JSON schema can be used to describe relationships between query parameters, I would really appreciate it if someone can point me to where that is described and perhaps an example. Or, if IDL4OAS is the officially recommended method of describing parameter relationships, let's just say so and close this issue and then all go have a drink to celebrate.

[MikeRalphson]

@SteveNay-vz

I don't want to do any disservice to the IDL solution offered by @AML14, but was anything done to support inter-parameter dependencies in v3.1?

No, it wasn't a focus during development of v3.1. That development started in October 2018, I don't think any non-breaking proposals were made in that time-frame, except adding a specification-extension, which of course, anyone is free to do at any time. We're always interested in people's experiences with feature pilots.

I'm not overly familiar with JSON schema (now fully supported in 3.1), but I spent a little time reading about dependencies and "applying subschemas conditionally" (if/then/else), and I don't see how they can help with inter-parameter dependencies. Unless I missed something, both of those concepts only apply within an object, but query parameters are completely separate objects, each with their own schema.

You haven't missed anything. Several people above have suggested using a single JSON Schema object to represent query parameters, path parameters and headers. That poses some problems (do you have three objects or one, how are style and explode handled - as a new JSON Schema vocabulary?) but I suspect it will certainly be discussed for v4.

Or, if IDL4OAS is the officially recommended method of describing parameter relationships, let's just say so and close this issue and then all go have a drink to celebrate.

IDL4OAS was only proposed during the last month of v3.1 development, when we were already into the RC phase. We haven't yet seen enough real-world feedback on it to even evaluate it properly, let alone recommend it. Darn, no drink for me. 😿

This issue is now over 6 years old. :-( OAS 3.1 was just released yesterday.

Unless GitHub have removed helpful features, this is a little redundant.

[AML14]

IDL4OAS is only as powerful as we, as a community, want it to be(come). Thanks to it, we've been able to develop tools that leverage the inter-parameter dependencies in the API, for example:

1. IDLReasoner: a tool for performing multiple analysis operations such as checking if the dependencies are satisfied in a request. So, for instance, it could be deployed on an API gateway to reject all requests that violate dependencies, without redirecting those to the respective service.
2. RESTest: a testing framework for REST APIs that generates requests satisfying/violating the inter-parameter dependencies of the web API operation. Internally, it uses IDLReasoner.

I just announced the opening of that issue in openapi-generator because I think automatic code generation is one of the greatest strengths of OpenAPI. If we can automatically generate the code in charge of checking if inter-parameter dependencies are satisfied or not in API clients and server stubs, that will be awesome.

[AML14]

For those interested in automatically generating built-in assertions in the source code of clients and servers, based on the IDL dependencies present in the OAS document (using our IDL4OAS extension), we just implemented a preliminary feature in OpenAPI Generator: OpenAPITools/openapi-generator#8722.

It currently targets Java (several frameworks of clients and servers), but it could be easily extended to other languages and frameworks in the future, especially taking @enriquebarba97's implementation as a reference.

All feedback welcome. Hope this is the beginning of some new cool stuff for the OAS ecosystem 🥳.

[vellala2000]

issues like these are critical for Open API adoption. Hope we will have solution for this in next version of openapi release.

[jon-jon-jon]

Find my solution here #182 (comment)

[kaiserbergin]

Would be really rad to have some movement on this as it's fairly common to have interdependencies among parameters. Translating and interpreting what's required in those scenarios is a bit difficult in the current state, outside of comments in descriptions.

[karenetheridge]

This can be done in the JSON Schema, if all the query parameters are treated as one "parameter" and passed to the schema evaluator as an object type.

The parameter deserialization process is not specified very clearly, but I do something similar when handling header parameters -- if the "type" keyword is present at the top level of the json schema for the header, and it is "array", then multiple values of that header are permitted and they are passed to the evaluator as an array. If it's "string", then only one header value is allowed; same thing for "number" or "integer", but in that case the parsed header value is also converted to a number (if possible) before being sent to the evaluator.

[handrews]

This will be addressed by the OAS 4 Moonwalk project. Active discussions include:

• One parameterSchema or one each for URL Parameters, headers and body? sig-moonwalk#20
• Arithmetic and relational inter-parameter dependencies and readability concerns sig-moonwalk#24
• Support for validation across parameters sig-moonwalk#31

As this change cannot be made in the 3.x line, I am closing it in favor of the Moonwalk discussions.