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 method | POST |
---|---|
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.
Property | Description | Example |
---|---|---|
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
Key | Value | Description |
---|---|---|
Content-Type | multipart/form-data | See request body above |
X-API-Key | Issued API Key | See API Authentication for further details |
Supported Formats
Source Formats
The Mapping API currently supports the following W3C standard source formats.
Source Format | Request Body Value |
---|---|
RDF N-Quads | n-quads |
RDF N-Triples | n-triples |
OWL/XML (see OWL/XML limitations below) | owl-xml |
RDF/XML | rdf-xml |
RDF TriG | trig |
RDF Turtle | turtle |
Target Formats
The Mapping API currently supports the following semantically linked target data formats (see RDF mapping limitations below).
Target Format | Request Body Value |
---|---|
JSON-LD | json-ld |
RDF N-Quads | n-quads |
RDF N-Triples | n-triples |
OWL/XML (see OWL/XML limitations below) | owl-xml |
RDF/XML | rdf-xml |
RDF TriG | trig |
RDF Turtle | turtle |
The Mapping API also currently supports the following property graph-based target data formats (see property graph mapping limitations below).
Target Format | Request Body Value |
---|---|
OntoPop Native Format | native |
GraphSON | graphson |
Vis.js | vis |
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:
Log into WebProtégé.
Open the relevant WebProtégé project.
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).
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).
In the section entitled "Share with specific people", share the project with OntoPop as follows:
Username: OntoPop
Privileges: ViewPress "Apply".
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 Format | Permitted File Extensions | Permitted MIME Types |
---|---|---|
RDF N-Quads | .nq | application/n-quads text/plain |
RDF N-Triples | .nt | application/n-triples text/plain |
OWL/XML | .owl | application/owl+xml text/xml |
RDF/XML | .owl, .rdf | application/rdf+xml text/xml |
RDF TriG | .trig | text/trig text/plain |
RDF Turtle | .ttl | text/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 Status | Response Message | Notes and Examples |
---|---|---|
200 OK | Ontology data successfully mapped. | See examples below. |
400 Bad Request | Neither a WebProtege project ID nor an ontology data file were provided. | |
400 Bad Request | Invalid source format provided. | See supported source formats above. |
400 Bad Request | Invalid target format provided. | See supported target formats above. |
400 Bad Request | Invalid ontology data file provided - file does not exist. | |
400 Bad Request | Invalid ontology data file provided - file is blank. | |
400 Bad Request | Invalid ontology data file provided - file size limit exceeded. | See file limitations above. |
400 Bad Request | Invalid ontology data file provided - file extension does not match the specified source format. | See file limitations above. |
400 Bad Request | Invalid ontology data file provided - MIME type does not match the specified source format. | See file limitations above. |
400 Bad Request | Invalid ontology data file provided - file is semantically invalid. | |
400 Bad Request | Invalid WebProtege project ID. | See WebProtégé integration above. |
403 Forbidden | Access 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 Error | An error was encountered when attempting to parse the ontology file. | |
500 Internal Server Error | An error was encountered when attempting to model the parsed ontology file as a simple property graph object. | |
500 Internal Server Error | Could not authenticate with WebProtege. | See WebProtégé integration above. |
500 Internal Server Error | Internal 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." .
...