Template parameters not allowed in query part of URL (OpenSearch-like)

[ycespb]

Dear all,
I have to say first of all that the specification is very interesting (we only discovered it recently) and we are looking forward for tool support to be aligned with this new version and apply it in current and future projects.

I wonder if the OAI specification could cover use cases for which today in our domain (Earth Observation) OpenSearch [1] Description Documents (OSDD) are used. This would require path templating also to be allowed in the query part or associating an actual parameter with the OpenSearch parameter.

We are currently relying heavily on OpenSearch 1.1 [1] and Parameter Extension of OpenSearch [2] for defining API, but the tendency now is to migrate this XML-based solution to a JSON equivalent and OAI comes very close...
The OSDD allows for URL templates like
template="http://example.com/search?q={searchTerms}", and only the parameter names between the {} are standardised by OpenSearch or related Open GeoSpatial Consortium specifications such as OGC 10-032r8 or OGC 13-026r8. Implementations are free to choose actual query parameter names.

For an OpenAPI description to be an alternative for an OSDD, it would be useful to be able to associate the actual query/path parameter names with their OpenSearch definition, thus associate q with searchTerms in the example. For the path parameters (in: path), this is already possible. However, for parameters which appear after the "?" (in: query), this is not allowed.

Either allowing in OAI to have paths with a query part with template parameters (which is similar to the x-ms-paths notation from Microsoft Azur [3]):

paths:
/example.com/search?q={searchTerms}&startRecord={startIndex}:
    get:
      parameters:
        - name: searchTerms   // 
          in: path             // this is currently not allowed in the query part of a "Path".
          description: Free text search term {searchTerms}.
          required: false
          type: string 

Alternatively, if extending the "path templating" cannot be envisaged, an association between q and searchTerms as in the OpenSearch Parameter Extension [2] could be done with a property such as x-value as below:

paths:
/example.com/search:
   get:
      parameters:
        - name: q
          x-value: "{searchTerms}"
          in: query
          description: Free text search term {searchTerms}.
          required: false
          type: string 

Another feature on our wishlist is to be able to distinguish values in enumerations (but also normal query parameter) from the way user interfaces would present them to users, e.g.
the Parameter Extension of OpenSearch uses:

<param:Option label="NASA Common Metadata Repository" value="EOP:NASA:CMR"/>

In OAI, there is no way to associate a "label" and it becomes:

          enum:
          - EOP:NASA:CMR

Have OpenSearch like "templating" capabilities been considered or could be envisaged? The current space Earth Observation community (e.g. CEOS [4]) which has invested a lot in the OpenSearch-like technology would then have a clear migration path to JSON/OAI while preserving the effort which went in defining the OpenSearch extensions with specific parameters for this domain....

regards,
Yves.

References used above:
[1]: http://www.opensearch.org/Specifications/OpenSearch/1.1
[2]: http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0/Draft_2
[3]: https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md
[4]: http://ceos.org/ourwork/workinggroups/wgiss/access/opensearch/

[MikeRalphson]

(Disclaimer, these are user comments not official OAS opinion.)

The key of an OAS pathItem object is a path, not a URL, so does not have a 'query part'. The URL query is always built dynamically from the parameters applicable to the operation. See this comment indicating this is highly unlikely to change.

The template parameter you discuss attaches meaning to the value (or position in a hypothetical template) of a querystring parameter, not its name. There is nothing stopping you creating a specification (vendor) extension similar to your x-value above, e.g. x-opensearch-type, but I'm guessing there is some tooling requirement for this to be interpreted in some way? Similarly with using the x-ms-paths extension, it is documented, but AFAIK has very limited tooling support beyond autorest.

As to your second point, where it pertains to enums, see this issue and linked issues.

[ycespb]

Thanks for these useful references about similar questions.

The tools that interpret these extensions (that currently interpret OpenSearch parameters in XML-based OSDD documents) are Client applications by space agencies like NASA and ESA and others that take such OSDD as input and propose a user interface to the user to search for satellite images, e.g. NASA CWICSmart.

We could indeed create a specification, let's say OpenAPI OpenSearch Extension, grouping together a number of vendor extensions needed to obtain a JSON equivalent of an OSDD, e.g. x-opensearch-type, an x-opensearch-query (equivalent to the os:query element), etc. Of course, existing OpenAPI (Swagger) tooling would not interpret these extensions. Do some OpenAPI (or Swagger) documentation-generation tools not have options to at least preserve such vendor extensions in generated documentation ? This would already be a nice advantage in addition to be able to exercise the API from the generated documentation. This does not exist today (to my knowledge) for OSDD documents.

Is there a kind of repository for such extensions for OpenAPI where they all can be found together ? and a standard way or template to define them ? E.g. OpenSearch 1.1 has also extensions and publishes them here for the interested users.

[MikeRalphson]

Is there a kind of repository for such extensions for OpenAPI where they all can be found together ? and a standard way or template to define them ?

This was discussed here, to summarise: not really, and not yet.

Do some OpenAPI (or Swagger) documentation-generation tools not have options to at least preserve such vendor extensions in generated documentation ?

I think the problem would be how to communicate / format that specification extension property. Some documentation tools (e.g. my own widdershins) take a template-based approach so can be extended to cover extensions, others may allow plugins to handle extensions.

I've collated a list of documented specification (vendor) extensions here but a proper repository a la OpenSearch or Schema.Org and/or a standard template would be great next steps.

[handrews]

This sort of thing is being addressed in OAS 4 Moonwalk as part of the operation signatures principle. Please join the discussions in that repository if you are still interested!