Mapping API

API for converting semantically linked ontology data.

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).

HTTP request methodPOST
API endpoint/mapping/map

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.

PropertyDescriptionExample
source (string) *Source format - see supported source formats below.rdf-xml
target (string) *Target format - see supported target formats below.graphson
file (multipart file)Ontology data file - see file limitations below.my-ontology.owl
webProtegeId (string)WebProtégé project ID - see WebProtégé integration below.abc123-def456-ghi789

Request Headers

KeyValueDescription
Content-Typemultipart/form-dataSee request body above
X-API-KeyIssued API KeySee API Authentication for further details

Supported Formats

Source Formats

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

Source FormatRequest Body Value
RDF N-Quadsn-quads
RDF N-Triplesn-triples
OWL/XML (see OWL/XML limitations below)owl-xml
RDF/XMLrdf-xml
RDF TriGtrig
RDF Turtleturtle

Target Formats

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

Target FormatRequest Body Value
JSON-LDjson-ld
RDF N-Quadsn-quads
RDF N-Triplesn-triples
OWL/XML (see OWL/XML limitations below)owl-xml
RDF/XMLrdf-xml
RDF TriGtrig
RDF Turtleturtle

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

Target FormatRequest Body Value
OntoPop Native Formatnative
GraphSONgraphson
Vis.jsvis

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.
Source FormatPermitted File ExtensionsPermitted MIME Types
RDF N-Quads.nqapplication/n-quads
text/plain
RDF N-Triples.ntapplication/n-triples
text/plain
OWL/XML.owlapplication/owl+xml
text/xml
RDF/XML.owl, .rdfapplication/rdf+xml
text/xml
RDF TriG.trigtext/trig
text/plain
RDF Turtle.ttltext/turtle
text/plain

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

HTTP StatusResponse MessageNotes and Examples
200 OKOntology data successfully mapped.See examples below.
400 Bad RequestNeither a WebProtege project ID nor an ontology data file were provided.
400 Bad RequestInvalid source format provided.See supported source formats above.
400 Bad RequestInvalid target format provided.See supported target formats above.
400 Bad RequestInvalid ontology data file provided - file does not exist.
400 Bad RequestInvalid ontology data file provided - file is blank.
400 Bad RequestInvalid ontology data file provided - file size limit exceeded.See file limitations above.
400 Bad RequestInvalid ontology data file provided - file extension does not match the specified source format.See file limitations above.
400 Bad RequestInvalid ontology data file provided - MIME type does not match the specified source format.See file limitations above.
400 Bad RequestInvalid ontology data file provided - file is semantically invalid.
400 Bad RequestInvalid WebProtege project ID.See WebProtégé integration above.
403 ForbiddenAccess to the specified WebProtege project ID is forbidden. Please share the WebProtege project with service@ontopop.com and try again.See WebProtégé integration above.
500 Internal Server ErrorAn error was encountered when attempting to parse the ontology file.
500 Internal Server ErrorAn error was encountered when attempting to model the parsed ontology file as a simple property graph object.
500 Internal Server ErrorCould not authenticate with WebProtege.See WebProtégé integration above.
500 Internal Server ErrorInternal server error.

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." .

...