Support interdependencies between query parameters

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.

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

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.

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.

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.

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

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

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.

+1 for cwarny simple suggestions

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

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

wow, good one, thanks

@craig-bayley

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

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

around it makes it much easier to read.

@ePaul

@ePaul Thanks for the tip. Done.

+1 Something like this would be very nice.

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.

@AML14

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.

@SteveNay-vz

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

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:

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

@enriquebarba97

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

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

Find my solution here #182 (comment)

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.

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.

Add descriptions for LookupArgumentSets

Add descriptions for LookupArgumentSets (#21)

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

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

tests: Remove /users/me/subscriptions/muted_topics from buggy endpoints.

Navigation Menu

Repository navigation

Support interdependencies between query parameters #256

53 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Support interdependencies between query parameters #256

Description

Activity

webron commented on Jan 29, 2015

cwarny commented on Jan 29, 2015

mohsen1 commented on Jan 29, 2015

cwarny commented on Jan 30, 2015

webron commented on Jan 30, 2015

iisurge commented on Jun 17, 2015

rcork commented on Sep 10, 2015

fractalawareness commented on Apr 27, 2016

filipnowakswissre commented on Oct 13, 2016

craig-bayley commented on Nov 23, 2016

filipnowakswissre commented on Nov 24, 2016

ePaul commented on Dec 12, 2016

craig-bayley commented on Dec 14, 2016

scottmas commented on Feb 14, 2017

53 remaining items

AML14 commented on Feb 16, 2021

SteveNay-vz commented on Feb 18, 2021

MikeRalphson commented on Feb 18, 2021

AML14 commented on Feb 19, 2021

AML14 commented on Jul 20, 2021

vellala2000 commented on Sep 30, 2021

jon-jon-jon commented on Nov 5, 2021

kaiserbergin commented on Nov 29, 2021

karenetheridge commented on Nov 29, 2021

handrews commented on Jan 24, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions