Annotating API to make it queryable

This page describes how you annotate your OpenAPI/Swagger definition to be queryable by the OpenRiskNet SPARQL service.

The very first entry will describe your service as an OpenRiskNet service.

openapi: 3.0.0
x-orn-@id: 'https://lazar.prod.openrisknet.org'
x-orn-@type: 'x-orn:Service'

and will be translated into:

subject	predicate	object
https://lazar.prod.openrisknet.org/	http://www.w3.org/1999/02/22-rdf-syntax-ns#type	http://openrisknet.org/schema#Service

The following code shows the annotation of a single route: (The whole API can be found here)

'/compound/{InChI}':
  get:
    x-orn-@type: 'x-orn:Compound'
    'x-orn:path': 'https://lazar.prod.openrisknet.org/compound/{InChI}'
    'x-orn:method': Get
    tags:
      - compound
    description: Get compound representation
    parameters:
      - $ref: '#/components/parameters/inchi'
      - $ref: '#/components/parameters/subjectid'
    responses:
      '200':
        description: OK
        content:
          application/json:
            'x-orn:returns': application/json
            schema:
              'x-orn:property': InChI
              type: string
              example: InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H

Each orn annotations will be used to translate lines of code into RDF triples. For parameters a reference was used. This reference fully described is:

parameters:
    inchi:
      name: InChI
      in: path
      description: InChI String
      required: true
      schema:
        type: string

Since inchi is a keyword and is described in the JSON-LD definition of the SPARQL service with an ontology URI it will be automatically converted.

{"@context": {
    "@vocab": "http://openrisknet.org/schema#",
    "x-orn": "http://openrisknet.org/schema#",
    "x-orn-@id": "@id",
    "x-orn-@type":"@type",

    "smiles": "http://semanticscience.org/resource/CHEMINF_000018",
    "inchi": "http://semanticscience.org/resource/CHEMINF_000113",
    "inchikey": "http://semanticscience.org/resource/CHEMINF_000059",
    "cas": "http://semanticscience.org/resource/CHEMINF_000446"
  }
}

subject	predicate	object
_:b1	http://semanticscience.org/resource/CHEMINF_000113	_:b10
_:b10	http://openrisknet.org/schema#description	InChI String^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#in	path^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#name	InChI^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#required	true^^http://www.w3.org/2001/XMLSchema#boolean