ga4gh / ga4gh/task-execution-schemas
Inconsistency between "GET /tasks" description and response definition
- Dominant language
- No language data
- Stars
- 95
- Forks
- 32
- PR merge metrics
- No merged PRs in 30d
Description
### Description
There is a minor inconsistency in the definition of the `GET /tasks` endpoint: the `responses` section for a `200` response expects a `tesListTasksResponse` object, which is itself an array of `tesTask` objects. Now, `tesTask` objects require the property `executors`, an object of type `tesExecutor`. But the `description` of the `view` query parameter in the same endpoint definition states that for view type `MINIMAL` only the `Task.id` (should perhaps be `tesTask.id`) and `Task.status` (`tesTask.status`) are to be returned. This makes automatic schema-based validation of the response impossible for that endpoint.
### Proposed solution
This is perhaps not quite easy to resolve, especially in Swagger 2.0, which does not allow defining different schemas for a response body. In OpenAPI 3.0, the `anyOf` and `oneOf` keywords can be used for that purpose (see [here](https://swagger.io/docs/specification/describing-responses/), [here](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) and [here](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)), although, unfortunately, not conditionally dependent of a request parameter (see [here](https://swagger.io/docs/specification/describing-responses/), bottom of page).
Perhaps the cleanest thing to do will be to define different schemas for `POST`ing and `GET`ting tasks, then set different requirements for the latter (e.g., `tesTaskResponse.id` and `tesTaskResponse.state`, but not `tesTaskResponse.executors`). This would also allow the `POST`-specific schema to get rid of the `id` property, which is anyway pointless to include, as it is, according to its description, expected to be generated by the implementation. Setting `id` as required in the response will allow a client or automatic validation framework in the service to ensure that the service, in fact, _did_ generate (and store!) a task ID and avoid potentially empty entries in a `MINIMAL` representation of the listed tasks (and elsewhere). Finally, once switching to OpenAPI 3.0, the `tesTaskResponse` schema could be decomposed into separate subschemas for the different views.
Other possible solutions:
* Make `executors` an optional parameter in `tes.Task`
* Make `executors` part of the `MINIMAL` response
Contributor guide
Research direction
Start by locating the OpenAPI definition for GET /tasks and compare its 200 response schema with the view query parameter description, especially the MINIMAL view and the required executors property. Review the proposed schema alternatives and determine which representation requirements should apply to GET and POST responses. Done means the specification consistently describes valid responses and supports schema-based validation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100