Mapping API

API for converting semantically linked ontology data.

Last updated: 01 May 2022Author: Jillur Quddus

Please note that the OntoPop backend open-source software project, which includes the event-driven data pipelines and APIs, is undergoing extensive redesign and refactoring as part of OntoPop Community 3.x in order to improve performance, security, extensibility and maintainability. As a result, the documentation on this page will be significantly updated. Please refer to the OntoPop Roadmap for further information.

1. Map

Overview

Map the given ontology-based semantically linked data from a given W3C standard source format (for example OWL RDF/XML) to a given RDF or property graph-based target format (for example RDF Turtle or GraphSON).

Path Variables

None

Request Body

Note that either file or webProtegeId must be provided. If neither are provided, then a HTTP 400 Bad Request response will be returned. If both are provided, then the WebProtege project ID will take priority and the file will be ignored.

Request Headers

Supported Formats

Source Formats

The Mapping API currently supports the following W3C standard source formats.

Target Formats

The Mapping API currently supports the following semantically linked target data formats (see RDF mapping limitations below).

The Mapping API also currently supports the following property graph-based target data formats (see property graph mapping limitations below).

WebProtégé Integration

The Mapping API supports WebProtégé projects as source inputs. If a WebProtégé project ID is provided, then OntoPop will programmatically export the given WebProtégé project from WebProtégé to an OWL RDF/XML file before performing the mapping operation.

In order for OntoPop to access the given WebProtégé project, it must be shared with OntoPop prior to requesting the Mapping API. In order to share the WebProtégé project with OntoPop, please perform the following actions:

1. Log into WebProtégé.

2. Open the relevant WebProtégé project.

3. In the address bar of your internet browser, make a note of the WebProtégé project ID contained within the WebProtégé URL (for example c9589912-e17b-4156-a1ab-fa5b10862f54).

4. Select "Share" from the toolbar (if the "Share" option is not visible or it is disabled/greyed-out, then you do not have the relevant privileges required to share the WebProtégé project. Please contact the owner of the WebProtégé project or another user who has "manage" privileges in order to share the WebProtégé project with OntoPop).

5. In the section entitled "Share with specific people", share the project with OntoPop as follows:
   Username: OntoPop
   Privileges: View

6. Press "Apply".

7. Provide the WebProtégé project ID noted in step 3 above when requesting the Mapping API - see request body above for further details.

Limitations

File Limitations

• Only files up to a maximum file size of 1MB are currently supported.
• If a WebProtege project ID is provided, then the OWL RDF/XML export file size from WebProtege must be no greater than 1MB.
• If a source ontology file is provided, then the file must have the correct file extension and MIME type based on the specified source format as listed in the following table.

OWL/XML Limitations

• If OWL/XML is specified as the source format, then the Mapping API currently only supports mapping to the RDF/XML target format. If any other target format is specified, then a HTTP 400 Bad Request response will be returned.
• If OWL/XML is specified as the target format, then the Mapping API currently only supports the RDF/XML source format. If any other source format is specified, then a HTTP 400 Bad Request response will be returned.

RDF Mapping Limitations

• If the JSON-LD or a RDF-based target format other than RDF Turtle is specified (for example RDF N-Quads), and if the mapping fails, then the target format returned will default to RDF Turtle syntax.

Property Graph Mapping Limitations

• If a property graph-based target format is specified (for example graphson), OntoPop will first convert the source file into OWL RDF/XML format before parsing it. The Mapping API currently only parses the following constructs:
  • Datatypes
  • Annotation Properties
  • Object Properties
  • Classes, Subclasses and Class Restrictions

Support for transforming the full OWL RDF/XML syntax to a property graph-based format will be available in OntoPop Community 3.x.

Responses

Examples

1. OWL RDF/XML File to GraphSON

Example request

$ curl -X POST -H 'X-API-Key: ABC123' -F 'source=rdf-xml' -F 'target=graphson' -F 'file=@/tmp/my-ontology.owl' https://api.ontopop.com/mapping/map

Example response (HTTP 200 OK)

{
    "graph": {
        "mode": "NORMAL",
        "vertices": [
            {
                "_id": "113334688201",
                "_type": "vertex",
                "_label": "class",
                "dataSource": "FFC",
                "definition": "A request made by a Customer or their legal representative for their personal information under data protection legislation.",
                "iri": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN",
                "name": "Data Subject Request"
            },
            {
                "_id": "138574800401",
                "_type": "vertex",
                "_label": "class",
                "definition": "Document storing the information conveyed between two or more parties.",
                "businessArea": "Communications",
                "comment": "A communication will typically have the Licence Holder (Highways England) as one of the parties.",
                "iri": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY",
                "name": "Communication Document"
            },
            {
                "_id": "108265040601",
                "_type": "vertex",
                "_label": "class",
                "example": "Develop connectivity between London and Inverness.",
                "comment": "A strategic goal that is achieved through a number of projects.",
                "dataSource": "Structures",
                "businessArea": "Maintain Plan",
                "definition": "A collection of projects or tasks undertaken to realise a strategic goal.",
                "iri": "http://webprotege.stanford.edu/R0qk59fxFmgNbyUncZoU8M",
                "name": "Programme"
            },
            ...
        ], 
        "edges": [
            {
                "_id": "1",
                "_type": "edge",
                "_label": "subclassOf",
                "_outV": "113334688201",
                "_inV": "138574800401",
                "weight": 1,
                "relationship": "Subclass of"
            },
            {
                "_id": "2",
                "_type": "edge",
                "_label": "subclassOf",
                "_outV": "113334688201",
                "_inV": "60577916701",
                "weight": 1,
                "relationship": "Provided by"
            },
            {
                "_id": "3",
                "_type": "edge",
                "_label": "subclassOf",
                "_outV": "138574800401",
                "_inV": "193344839801",
                "weight": 1,
                "relationship": "Provided to"
            },
            ...
        ]
    }
}

2. OWL RDF/XML File to Vis.js Dataset

Example request

$ curl -X POST -H 'X-API-Key: ABC123' -F 'source=rdf-xml' -F 'target=vis' -F 'file=@/tmp/my-ontology.owl' https://api.ontopop.com/mapping/map

Example response (HTTP 200 OK)

{
    "graph": {
        "vertices": [
            {
                "id": "113334688201",
                "type": "class",
                "label": "Data Subject Request",
                "dataSource": "FFC",
                "definition": "A request made by a Customer or their legal representative for their personal information under data protection legislation.",
                "iri": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN"
            },
            {
                "id": "138574800401",
                "type": "class",
                "comment": "A communication will typically have the Licence Holder (Highways England) as one of the parties.",
                "businessArea": "Communications",
                "definition": "Document storing the information conveyed between two or more parties.",
                "label": "Communication Document",
                "iri": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY"
            },
            {
                "id": "108265040601",
                "type": "class",
                "businessArea": "Maintain Plan",
                "label": "Programme",
                "dataSource": "Structures",
                "definition": "A collection of projects or tasks undertaken to realise a strategic goal.",
                "comment": "A strategic goal that is achieved through a number of projects.",
                "example": "Develop connectivity between London and Inverness.",
                "iri": "http://webprotege.stanford.edu/R0qk59fxFmgNbyUncZoU8M"
            },
            ...
        ], 
        "edges": [
            {
                "id": "1",
                "type": "subclassOf",
                "from": "113334688201",
                "to": "138574800401",
                "weight": 1,
                "relationship": "Subclass of"
            },
            {
                "id": "2",
                "type": "subclassOf",
                "from": "113334688201",
                "to": "60577916701",
                "weight": 1,
                "relationship": "Provided by"
            },
            {
                "id": "3",
                "type": "subclassOf",
                "from": "138574800401",
                "to": "193344839801",
                "weight": 1,
                "relationship": "Provided to"
            },
            ...
        ]
    }
}

3. OWL RDF/XML File to OntoPop Native Format

Example request

$ curl -X POST -H 'X-API-Key: ABC123' -F 'source=rdf-xml' -F 'target=native' -F 'file=@/tmp/my-ontology.owl' https://api.ontopop.com/mapping/map

Example response (HTTP 200 OK)

{
    "id": 1,
    "latestGitWebhookId": 0,
    "vertices": {
        "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN_1": {
            "iri": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN",
            "ontologyId": 1,
            "vertexKey": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN_1",
            "vertexId": 113334688201,
            "latestGitWebhookId": 0,
            "properties": {
                "label": "Data Subject Request",
                "definition": "A request made by a Customer or their legal representative for their personal information under data protection legislation.",
                "dataSource": "FFC"
            },
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY_1": {
            "iri": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY",
            "ontologyId": 1,
            "vertexKey": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY_1",
            "vertexId": 138574800401,
            "latestGitWebhookId": 0,
            "properties": {
                "comment": "A communication will typically have the Licence Holder (Highways England) as one of the parties.",
                "businessArea": "Communications",
                "definition": "Document storing the information conveyed between two or more parties.",
                "label": "Communication Document"
            },
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        "http://webprotege.stanford.edu/R0qk59fxFmgNbyUncZoU8M_1": {
            "iri": "http://webprotege.stanford.edu/R0qk59fxFmgNbyUncZoU8M",
            "ontologyId": 1,
            "vertexKey": "http://webprotege.stanford.edu/R0qk59fxFmgNbyUncZoU8M_1",
            "vertexId": 108265040601,
            "latestGitWebhookId": 0,
            "properties": {
                "example": "Develop connectivity between London and Inverness.",
                "businessArea": "Maintain Plan",
                "comment": "A strategic goal that is achieved through a number of projects.",
                "label": "Programme",
                "definition": "A collection of projects or tasks undertaken to realise a strategic goal.",
                "dataSource": "Structures"
            },
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        ...
    }, 
    "edges": [
        {
            "sourceVertexKey": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN_1",
            "sourceVertexId": 113334688201,
            "targetVertexKey": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY_1",
            "targetVertexId": 138574800401,
            "ontologyId": 1,
            "latestGitWebhookId": 0,
            "properties": {},
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        {
            "sourceVertexKey": "http://webprotege.stanford.edu/R0hGCuAkhsiBUbd7pftEpN_1",
            "sourceVertexId": 113334688201,
            "targetVertexKey": "http://webprotege.stanford.edu/RBJ3sWyEdjzo3HjkcABim8C_1",
            "targetVertexId": 60577916701,
            "ontologyId": 1,
            "latestGitWebhookId": 0,
            "properties": {
                "relationship": "Provided by"
            },
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        {
            "sourceVertexKey": "http://webprotege.stanford.edu/R0jI731hv09ZcJeji1fbtY_1",
            "sourceVertexId": 138574800401,
            "targetVertexKey": "http://webprotege.stanford.edu/RY4x5rU5jNH9YIcM63gBgJ_1",
            "targetVertexId": 193344839801,
            "ontologyId": 1,
            "latestGitWebhookId": 0,
            "properties": {
                "relationship": "Provided to"
            },
            "dateLastUpdated": "2022-05-05 12:30:06"
        },
        ...
    ]
}

4. OWL RDF/XML File to RDF Turtle

Example request

$ curl -X POST -H 'X-API-Key: ABC123' -F 'source=rdf-xml' -F 'target=turtle' -F 'file=@/tmp/my-ontology.owl' https://api.ontopop.com/mapping/map

Example response (HTTP 200 OK)

@prefix :           <http://webprotege.stanford.edu/project/96Ytr9AQdNv8valtcgFhzp#> .
@prefix dc:         <http://purl.org/dc/elements/1.1/> .
@prefix owl:        <http://www.w3.org/2002/07/owl#> .
@prefix rdf:        <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:       <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos:       <http://www.w3.org/2004/02/skos/core#> .
@prefix webprotege: <http://webprotege.stanford.edu/> .
@prefix xsd:        <http://www.w3.org/2001/XMLSchema#> .

webprotege:R8UlzVcWWjnYzxJxqtXIIFd
        rdf:type            owl:ObjectProperty ;
        rdfs:label          "Managed within" ;
        rdfs:subPropertyOf  webprotege:RDWUwRcLiaC4DTUFG8M99SF ;
        webprotege:RtMeQat8p1tL74b64dS2qs
                "Participation" ;
        skos:definition     "Relationship used to define the Entity inside which the activities related to other Entities are controlled." .

webprotege:R7ziZlwBCU3dDShTGeoBjYR
        rdf:type         owl:Class ;
        rdfs:label       "Drawing" ;
        rdfs:subClassOf  webprotege:RFC5Q9hfMGLXk65hXqNCzp ;
        webprotege:R9S1rcldeHXCMGJUZEkvaWJ
                "Sketch" ;
        skos:definition  "A Design Representation intended to visually communicate the properties of an Asset or system of Assets." .

webprotege:R3WvW1lERMZ6UCSsaAdkx1
        rdf:type         owl:Class ;
        rdfs:label       "Acquisition" ;
        rdfs:subClassOf  webprotege:R8N1a0K78gZZbVLw2P1NkTX ;
        rdfs:subClassOf  [ rdf:type            owl:Restriction ;
                           owl:onProperty      webprotege:R7cbyWVOLsYCR1NFY11TBjJ ;
                           owl:someValuesFrom  webprotege:R93SkoUnFXM1KEjUDb2Ij3n
] ;
        rdfs:subClassOf  [ rdf:type            owl:Restriction ;
                           owl:onProperty      webprotege:RbjcXDTrplTouTeWRoMMe7 ;
                           owl:someValuesFrom  webprotege:R7aUPF2nCTl0LhxRiIVdzpc
] ;
        rdfs:subClassOf  [ rdf:type            owl:Restriction ;
                           owl:onProperty      webprotege:R7uRVbFaeQ4xCgAEayawrZ3 ;
                           owl:someValuesFrom  webprotege:RDUwHG4VnwQTyDDhhsWSwgS
] ;
        rdfs:subClassOf  [ rdf:type            owl:Restriction ;
                           owl:onProperty      webprotege:R7cbyWVOLsYCR1NFY11TBjJ ;
                           owl:someValuesFrom  webprotege:RY4x5rU5jNH9YIcM63gBgJ
] ;
        webprotege:R8AWk6f00nQhiAoDl6ujohI
                "Estates Development phase" ;
        webprotege:RB4qRK0cMJE67o1Bc9MmGDD
                "Estates" ;
        webprotege:RkKVruwOD8lCCdsbyX0lwY
                "Maintain Operate Construct Finance" ;
        skos:definition  "The action of an Entity becoming the owner of Land, an Asset, or a Vehicle through a Legal Document and/or Transaction." .

webprotege:R7msJHfQBx9IyBoi6uDKJ2m
        rdf:type         owl:Class ;
        rdfs:label       "Financial Value" ;
        rdfs:subClassOf  webprotege:R1qJMsQqC5KurNMw9vwNbf ;
        rdfs:subClassOf  [ rdf:type            owl:Restriction ;
                           owl:onProperty      webprotege:RuflVNuPASFn75l7LznQc0 ;
                           owl:someValuesFrom  webprotege:RJVpffoomVWohIDaJCykd9
] ;
        webprotege:RkKVruwOD8lCCdsbyX0lwY
                "Maintain" ;
        skos:definition  "The monetary benefit of a Project, Programme, or goal to Stakeholders and Customers." .

...