schemaUrl Property to document the API schema used by the service

[susheel]

I feel it may be worth adding the explicit URL to the API schema used by the service. This would allow clients to detect the API schema used by the service and self-configure. This could point to the GA4GH YAML spec or a local copy that may add non-breaking extensions. See example below:

schemaUrl:
  type: string
  description: URL of the schema of this service (RFC 3986 format).

Related GA4GH DRS /service-info PR #277 discussion.

Resolves #26

[andrewyatz]

I can understand the use-case here. Would this be a JSON-schema or Swagger API declaration?

[susheel]

Ideally both.

I was only thinking along the lines of the OpenAPI/Swagger YAML definitions in this iteration as it would give the client both the JSON type definitions and the API path-spec in a single file.

Most OpenAPI client frameworks can already handle the Swagger/OpenAPI YAMLs natively for self configuration. Not sure about JSON schema, which I have only seen for data validation.

I suspect we would need a separate JSON schema support when we start dealing with different type definitions for multiple versions of the same API. Let's cross that bridge when we get there.

[andrewyatz]

Then my bigger question is how would you know which model in the OpenAPI spec refers to service-info? I guess we'd look for the service-info endpoint, find the associated payload & parse that. It's quite a complicated path to resolving it versus a JSON schema, which would directly refer to the response modelled. I guess what I'm missing here is a worked through example of how someone would go about using this. Otherwise I'd push to not integrating it into this current version spec and waiting to see what happens in PRC.

…

On Mon, 10 Jun 2019 at 17:18, Susheel Varma ***@***.***> wrote: Ideally both. I was only thinking along the lines of the OpenAPI/Swagger YAML definitions in this iteration as it would give the client both the JSON type definitions and the API path-spec in a single file. Most OpenAPI client frameworks can already handle the Swagger/OpenAPI YAMLs natively for self configuration. Not sure about JSON schema, which I have only seen for data validation. I suspect we would need a separate JSON schema support when we start dealing with different type definitions for multiple versions of the same API. Let's cross that bridge when we get there. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#27?email_source=notifications&email_token=AABLSGIINQUNKXQYN7SSDDLPZZ5FFA5CNFSM4HWJMT22YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXKLN5I#issuecomment-500479733>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABLSGJMW7C73NERDRXK6O3PZZ5FFANCNFSM4HWJMT2Q> .

[susheel]

Honestly, I would have liked to have the service expose a URL to underlying JSON schema, hence the original name (schemaUrl). I eventually shied away from this at this point in time, as it would mean a lot more upfront work, and as AFAIK none of the current GA4GH API specs does this natively:

1. Convincing GA4GH spec maintainers and implementors to provide a JSON schema in addition to the swagger YAML. This can be done automatically at build time, see WES #137

2. A lot more effort will be needed to embed the JSON schema @context and @type information for each model object in the API JSON response so that they can be validated against the provided JSON schema. This is especially needed when we deal with request-response chains that may support multiple versions, i.e. when we have to send the response of one service to another for processing. e.g. TRS v1 response as a request to WES service that supports both TRS v1 and v2. The WES service will need to know which version of the object it is processing.

That being said, JSON schema only provides useful data model validation but does not provide any hints on the API path-spec itself. The Swagger/OpenAPI YAML spec provides both.

We are primarily interested in using this mechanism to introduce local Swagger path-spec and model x-extensions that would still be compatible with the GA4GH community spec. Our clients will be able to use the service-provided schemaUrl to make use of (non-breaking) extended features, while still allowing GA4GH community clients with hard-coded common GA4GH spec. Rather than relying on clients to manually hard-code this from a separate location, it would be great if this was available from the service endpoint itself. The default can still point to the GA4GH common spec.

Happy for this to stay in the backlog for a future date.

[andrewyatz]

On the 1st point we should keep an eye on the WES issue. I know there are problems with openapi and JSON schema compatibility but this is in the process of being resolved.

On the second point I thought @context and @type are part of JSON-LD and schema.org, not JSON schema. In the case of the later they are controlled using the $schema and $id attributes.

I'm afraid to say that think it's better to define what we're trying to achieve here and the use-case we're looking to solve than injecting a new attribute late on in the process. Sorry.

[susheel]

Sorry, I meant $schema and $id. I was only hoping it will go through in this round. Happy for this to stay in the backlog for a future date.

[andrewyatz]

Okay. I think best to retain this for future versions once we know more about the place of JSON schema. Might be good to collaborate with Schema Blocks on this.

…

On Tue, 11 Jun 2019 at 10:54, Susheel Varma ***@***.***> wrote: Sorry, I meant $schema and $id. I was only hoping it will go through in this round. Happy for this to stay in the backlog for a future date. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#27?email_source=notifications&email_token=AABLSGJRW6OWNQBAQO4UAJTPZ5Y67A5CNFSM4HWJMT22YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXMS33Y#issuecomment-500772335>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABLSGK73LLNJELEYATHXODPZ5Y67ANCNFSM4HWJMT2Q> .