OpenAPI example

[huberrob]

Just a short question regarding the OpenAPI example:

I wonder if we should't have in service-doc the URL for the OpenAPI spec per se there which is (for v3.1.0): https://spec.openapis.org/oas/v3.1.0 instead of the implementation specific API doc UR

I am asking because we have in the OAI-PMH for service-doc the URL https://www.openarchives.org/OAI/openarchivesprotocol.html

[hvdsomp]

I am really not convinced. The reason being that the PMH spec (service-doc) really defines the interface. Without it an agent can't proceed. That is not the case with an OpenAPI endpoint because. Using the EMBL-EBI example from the FAIRiCat spec:

• the human readable definition of the interface (comparable to the PMH spec) is at https://www.ebi.ac.uk/biomodels/docs/
• both the human readable and the machine readable interface specification declare they adhere to OpenAPI specification version 3

As such, I do not think there is a need to refer to the OpenAPI spec because it is referenced in the both API documentations. Those API documentations are essential because without them (just like without the PMH spec), an agent can't proceed.

[huberrob]

Not sure if this helps, but a group seems to have collected a list of URIs related to services here: https://github.com/OSGeo/Cat-Interop/blob/master/LinkPropertyLookupTable.csv

[hvdsomp]

I have been thinking more about this and came to the conclusion that @huberrob's above suggestion is actually pertinent. In a typical approach, when a client wants to discover whether a repository supports an interoperability affordances that it can handle, the client will scan the FAIRiCat for the URL of a specification on which the affordance is based, i.e. the URL of the PMH spec when it wants to PMH-harvest, the URL of the Sitemaps Protocol when it wants to crawl, etc. This capability does not exist for OpenAPI affordances when the service-doc link only points at the human-readable description of the API that is described in a machine-readable manner by the OpenAPI document provided using the service-desc link. Therefor, there indeed must be a service-doc link that points to the OpenAPI specification, as suggested by @huberrob . The human-readable specification of the actual API can be provided using a second service-doc link. I updated the FAIRiCat specification accordingly at https://signposting.org/FAIRiCat/.