feat: add alternative schema for array items in RunListResponse

[uniqueg]

Alternative to #172 Closes #165

This PR differs from #172 in the following ways:

• A separate schema RunSummary is defined, to be used specifically for the runs array items in RunListResponse
• RunSummary extends RunStatus (not modified!) with required additional fields
• For backward compatibility, either RunSummary or RunStatus (anyOf) are acceptable responses for GET /runs
• Next to start_time and end_time, also workflow name and tags are included in the extended response; workflow_url was not included, as it can point to a local object and its support would therefore require WES to serve objects (up for debate of course, following #172 and #165)

Taken together, this proposal avoids or partly addresses the following concerns raised against #172:

• "Proposal has side effects:" By using a separate schema to accommodate the additional metadata fields to be returned in run list responses, the RunStatus schema remains untouched, thus retaining the behavior of GET /runs/{run_id}/status (which also uses RunStatus).
• "Implementers may choose to ignore added fields": While implementers can still return RunStatus instead of RunSummary (or indeed any other response that has the run_id and state properties) in run list responses for backward compatibility (anyOf), this PR adds a couple of measures to more strongly encourage the use of the new extended schema. In particular,
  • A DEPRECIATION WARNING is added to the description of RunListResponse, informing implementers that the use of RunStatus in RunListResponse will be discontinued in favor of RunSchema only.
  • The new schema requires the additional fields in RunSummary, which - together with the depreciation warning - should tell every implementer clearly where the specs will be going in this respect; indeed, as soon as support for RunStatus in RunListResponse is removed (a simple change), any compliant implementation MUST provide these additional fields in their run list responses.

It does NOT address the concern that "clients may not agree with selection of fields".

[uniqueg]

Thanks @patmagee :) I would still like to prepare a PR for the solution proposed here, before reaching out to implementers to vote. But I'm afraid it's gonna take me another two weeks or so.

[patmagee]

@uniqueg can you please rebase this on develop

[patmagee]

@wleepang @cjllanwarne I wonder what your thoughts are on this modified PR?

[wleepang]

I think tags is more important than name for this response. (see my comment above).

From a client perspective, runid, (start|end)_time, and status are certainly must haves. I'd say tags is required and it is strongly recommended that "run_name" and "workflow_name" tags are included.

[uniqueg]

I think tags is more important than name for this response. (see my comment above).

From a client perspective, runid, (start|end)_time, and status are certainly must haves. I'd say tags is required and it is strongly recommended that "run_name" and "workflow_name" tags are included.

I'm with you. It seems to me like we all agree and it's mostly a semantic argument. The main point is that we want to encourage implementers as much as possible to make this info available, without making their life unduly hard if, for whatever reason, they can't. So let it be in tags :)

[patmagee]

@uniqueg once you update this PR to remove name and make fields like start_time and end_time optional, I will go ahead and merge it!

[uniqueg]

@uniqueg once you update this PR to remove name and make fields like start_time and end_time optional, I will go ahead and merge it!

Done