Several requests in OOAPI (both in v4 and v5) support query parameters that have an array as the expected value. E.g. ?expand=person,offering. In this example an array of person and offering is passed to the expand query parameter.
In the documentation for such query parameters we state:
Optional properties to expand, separated by a comma
The default serialization scheme for query parameters is form with explode. According to this default, the correct way to pass person and offering to the expand query parameter would be: ?expand=person&expand=offering. Which does not correspond to what we are suggesting in the documentation.
This has consequences for automatic tooling that relies upon the OOAPI specification, such as validation.
Version
v5
Usecase
Making sure tools such as validators work correctly.
Which institutions support this change?
No response
Proposed solution
Add the following two parameters to the relevant parameter specifications in the yaml files:
style: form
explode: false
Requests and responses
All requests that have query parameters that accept an array of values.
Organization
SURF
Project
n/a
Contact Details
jelmer.deronde@surf.nl
Short description
Several requests in OOAPI (both in v4 and v5) support query parameters that have an array as the expected value. E.g.
?expand=person,offering
. In this example an array ofperson
andoffering
is passed to theexpand
query parameter.In the documentation for such query parameters we state:
However, the OpenAPI specification supports multiple methods of parameter serialization, see: https://swagger.io/docs/specification/serialization/
The default serialization scheme for query parameters is
form
withexplode
. According to this default, the correct way to passperson
andoffering
to theexpand
query parameter would be:?expand=person&expand=offering
. Which does not correspond to what we are suggesting in the documentation.This has consequences for automatic tooling that relies upon the OOAPI specification, such as validation.
Version
v5
Usecase
Making sure tools such as validators work correctly.
Which institutions support this change?
No response
Proposed solution
Add the following two parameters to the relevant parameter specifications in the yaml files:
Requests and responses
All requests that have query parameters that accept an array of values.
What is your question for the OOAPI work group?
No response