Semantic interoperability

Data exchange between data warehouses, software tools and the end user adopted by OpenRiskNet has to follow a very flexible approach to avoid time-consuming development of input and output routines specifically for OpenRiskNet. This is achieved by basing the complete exchange on application programming interfaces (APIs), which follows the same concept independent of whether data is requested from data sources (data APIs) or software tools are executed (software APIs). These APIs are annotated by a semantic layer, which can be used by the user or other services for the communication between tools and to get information on the capabilities of the tools and the input/output options.

After careful evaluation, a combination of two approaches was selected that extends the industry standard OpenAPI (formerly Swagger) and turns the main openapi.json description files into the semantic web standard JSON-LD by providing a JSON-LD context. This allows us to combine the tools of two existing, powerful, but so far independent sets of technology stacks: OpenAPI on the one hand to cover the technical details of a REST API with a big toolset around automatic creation of tools and documentation; and on the other hand JSON-LD and the semantic web technologies around the RDF data model and in particular SPARQL queries to query flexible knowledge graphs.

Creation of an OpenRiskNet Service Description is a technically straightforward process if an OpenAPI/Swagger definition already exists for a REST API (which is a very common case). A document explaining the details of the semantic annotation for REST API authors is work in progress and will be made available here. A minimal JSON-LD context for an OpenRiskNet-compliant service will look as given in the listing below. It consists of a set of alias definitions to make JSON-LD keywords, that are illegal JSON keys for an OpenAPI.json/Swagger.json, valid by prefixing them with “x-orn” (lines 4 and 5 in the listing below). To really use the power of semantic API annotation, every service provider should then additionally define a subset of the json-keys used in the response body and provide meaningful ontology terms for them (see the “smiles” and “inchi” examples).

{"@context": {
    "@vocab": "",
    "x-orn": "",
    "x-orn-@id": "@id",

    "smiles": "",
    "inchi": "",
    "inchikey": "",
    "cas": ""

To facilitate experimentation and validate the feasibility of the OpenRiskNet service description concept, a web-based UI tool has been created called the OpenRiskNet Query Tester. It allows authoring of OpenRiskNet Service Description documents as well as the authoring and execution of SPARQL queries against these service descriptions: