Provide JSON Schema definitions of the WES data model

[susheel]

Provide JSON Schema definitions to help WES clients validate WES request/responses.

[jaeddy]

@susheel - what's the benefit of storing this separately from the definitions (or components in OpenAPI 3) section of the spec YAML? When converted to JSON, this section provides exactly the JSON Schema definitions you describe.

I'd be a little worried about the two documents potentially getting out of sync.

[susheel]

It is mainly to allow a non-swagger client to still validate the JSON response without processing the swagger spec to extract the JSON schema.

I am planning to raise this as a separate proposal but just wanted to give you the context of where I'm going with this. Long-term I see the need to embed the schema version into the JSON response to allow a client to validate and process cross-service JSON responses. Example below:

{
  "@context": "http://ga4gh.cloud/wes/v1",
  "id": "..."
  ...
}

http://ga4gh.cloud/wes/v1 is just a well-known direct url path to the JSON schema defenition of the JSON response.

This is especially needed when we get a TRS v1 response to be sent to a WES service that can process both TRS v1 and v2 JSON data. Ditto for WES <--> TES and/or DRS.

I strongly feel this is better than relying on the current suggestion of using baseURL versions /ga4gh/wes/v1 path as downstream services will not know which version of the upstream response they are processing. JSON schema is needed for this that know which swagger spec was used to produce the JSON body.

[briandoconnor]

@susheel how does this relate to ga4gh/data-repository-service-schemas#264 ? Also, can you just generate this JSON as part of the documentation build system?

[jaeddy]

Thanks, @susheel! I like this vision, though would like to see it as part of the build process (the JSON file doesn't need to be under version control — but we can certainly handle the Swagger processing to save clients the trouble). I'd be OK merging your PR for now and dealing with the build/deploy/hosting updates in a separate ticket.

@briandoconnor — I do think this relates to what the Discovery WS is trying to enable, but not sure exactly how it fits with /service-info. Might be worth chatting with them some more. This could also be a topic on which the Smart API folks could lend some insight.

[susheel]

@briandoconnor @jaeddy Yes, I believe this can be generated from the build process. I use https://github.com/instrumenta/openapi2jsonschema

[jaeddy]

I'll merge develop into master sometime today or tomorrow, which should close this issue, then address the build changes in #137.

[ruchim]

hey @jaeddy -- do you feel this issue should be closed? And also #137 -- they both seem linked.

[uniqueg]

Related: ga4gh/TASC#43

[uniqueg]

I very much like the HATEOAS aspects of @susheel's suggestion, but given that tooling around OpenAPI is excellent and includes converters for JSON Schema, the main point of the issue seems redundant to me in 2024.