Invalid Syntax in includeResultsetResponses

[datsirul]

The endpoints that use the includeResultsetResponses parameter contain invalid OpenAPI syntax.

These include the following files:

• analyses/endpoints.yaml
• biosamples/endpoints.yaml
• genomicVariations/endpoints.yaml
• individuals/endpoints.yaml
• runs/endpoints.yaml

Existing Syntax:

includeResultsetResponses:
  $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses

Corrected Syntax:
As this object is a parameter definition, it should be defined as a parameter object in the OpenAPI specification. The correct syntax should be:

includeResultsetResponses:
  name: includeResultsetResponses
  in: query
  schema:
    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses

Reference:
OpenAPI Specification - Describing Parameters

Note:
After fixing the .yaml files, the .json should be fixed as well by running the schema conversion script located in the bin folder.

[jrambla]

Hi Daniel

Please do the PR.
I see that you are working with the "transcribed to yaml" version that eventually became the "source" ... I actually haven't tested that, and I don't know if anyone else has done it, hence, it is likely that errors pop up.

[mbaudis]

@jordi @datsirul While in principle it is great to spot & correct this, the overarching question we had previously was about maintaining the OpenAPI documents at all. In the Ascona developer session the conclusion was basically that:

• the Beacon schema (esp. model) cannot be defined in OpenAPI (at least not reasonably)
• OpenAPI documents (endpoints ...) replicate definitions done elsewhere (map ...)
• the "fire up a UI from the specs" isn't really a use case for Beacon, besides testing scenarios
• none of the implementers/devs actually make use of them
• for tests we need dedicated tools
• OpenAPI specifications can be generated
• OpenAPI specs are misleading since many aspects of Beacon (parameter use & combination, aggregation, terminologies ...) need to be understood from other parts of the spec. and/or documentation

... just paraphrasing & YMMV on some of the arguments. But the longstanding question about ditching OpenAPI in one of the next releases should be answered (which it was) and documented as the path forward. OTOH it could be nice to keep OpenAPI docs as generated artifacts, but not as edited ones...

[zykonda]

• the Beacon schema (esp. model) cannot be defined in OpenAPI (at least not reasonably)
• OpenAPI documents (endpoints ...) replicate definitions done elsewhere (map ...)
  @mbaudis Those two points are not clear to me. While OpenAPI helps to define the Beacon Framework (endpoints, request, response, parameters, entities and types used), the internal data representation is not dictated by the standard and should be mapped to entities defined by standards. Or what is that "Beacon schema (esp.model)" are you referring and what cannot be defined?

[jrambla]

@mbaudis @zykonda:
Please continue the conversation in Discussion #40