ga4gh / ga4gh/task-execution-schemas

Inconsistency between "GET /tasks" description and response definition

Open
#136 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.