# m2rdf - Model to RDF

m2rdf is a web-service which allows the transformation of models to an RDF representation.


## Features

* Transformation of ADOxx models to the RDF reprsentation developed in the ComVantage project.
  - For more information see section "Recommended approach for Serialisation of models as Linked Data" of the public ComVantage deliverable "D3.1.2 - Specification of Modelling Method Including Conceptualisation Outline" available [through the OMiLAB page](https://austria.omilab.org/psm/content/comvantage/info?view=publications)


## Usage

To transform an ADOxx model send an HTTP POST request to this endpoint (same URL) which contains the relevant inputs in its body.

Relevant inputs:
* The model(s) that should be transformed. Currently only models in the ADOxx XML format are supported (see [Supported source types](#supported-source-types)). Can be either provided directly or through a link, with the link taking precedence. This is pretty much mandatory.
* The desired target RDF format to be returned (see [Supported target types](#supported-target-types)). If none is provided then TriG (`text/trig`) will be used.
* A base URL to be used for identifiers for the elements of a model. If none is provided then one will be generated (but it might not be pretty).
* A description of the meta-model the models correspond to. If none is provided then the models will still be transformed, however the quality of the result might not be as good. See [Supported meta-model types](#supported-meta-model-types) and [Using with "mm2rdf - Metamodel to RDF"](#using-with-"mm2rdf---metamodel-to-rdf") for more information.
* A URL specifying the graphname of the meta-model graph. This is only relevant if a meta-model description is provided. If this input is missing then the graphname will be guessed based on the provided meta-model RDF description.
* Specify whether the URLs should be "beautified" (default: false). It replaces often used characters with simpler alternatives (removing `(` and `)`, replacing single spaces and `.` with `_` and replacing `&` with `+`) to create nicer looking URLs, but could lead in some cases to two elements getting the same URL (e.g. "A&B" and "A+B" would both be encoded into "A+B" or "C D" and "C_D" would both be encoded into "C_D"). **Important:** this setting has to be the same as the one used for the transformation of the used meta-model! If the identifiers used in the meta-model RDF don't contain parts like `%20` (escape sequence for a space) then it most likely used the "beautified" URLs.

The inputs should be provided through valid XML (`application/xml`) in the following structure (order irrelevant):
```xml
<m2rdf>
  <targettype><!-- the media type of the desired target RDF format for the model(s) --></targettype>
  <baseurl><!-- the base URL to be used when generating identifiers for the elements of a model --></baseurl>
  <beautifyurls><!-- either true or false to specify whether URLs should be "beautified" by replacing certain characters with more common ones --></beautifyurls>
  <models>
    <!-- containing the model description in one of the supported types -->
    <!-- alternatively the "model" element can contain an attribute "location" that contains a URL where the model data can be retrieved -->
  </models>
  <graphname><!-- the URL of the meta-model graph to be used --></graphname>
  <metamodel>
    <!-- containing the meta-model description in one of the supported types. If the description is a non-XML type (Turtle, TriG etc.) then it is recommended to provide the content as <![CDATA[ ... ]]> and the correct media type must be provided through the "type" attribute in the "metamodel" element -->
    <!-- alternatively the "meteamodel" element can contain an attribute "location" that contains a URL where the meta-model data can be retrieved. It is recommended to also provide the correct media type through a "type" attribute in the "metamodel" element, so that it is loaded properly -->
  </metamodel>
</m2rdf>
```


### Supported source types

Only the XML format as generated through the ADOxx 1.5 XML Export of one or several models is supported right now. Either the style from the tool with `<ADOXML>` as the root element or from the AdoScript documentation component with `<adoxml>` as the root element.


### Supported target types

The following target media types are supported (Triple and Quad based):
* text/turtle - Turtle (.ttl) - Triples
* application/rdf+xml - RDF XML (.rdf) - Triples
* application/n-triples - N-Triples (.nt) - Triples
* application/ld+json - Linked Data JSON (.jsonld) - Quads
* text/trig - TriG (.trig) - Quads
* application/n-quads - N-Quads (.nq) - Quads
* application/trix+xml - TriX (.trix) - Quads
* application/rdf+thrift - Apache Thrift (.trdf) - Quads

Note that the transformation puts evey model in a separate graph. If a Triple based approach is used then the statements are no longer assigned to a specific graph, so the distinction between different graphs (and thus models) will be lost.


### Supported meta-model types

The following meta-model media types are supported:
* application/x.adolib15+xml - ADOxx 1.5 Library XML - will be transformed
* text/turtle - Turtle (.ttl) - Triples
* application/rdf+xml - RDF XML (.rdf) - Triples
* application/n-triples - N-Triples (.nt) - Triples
* application/ld+json - Linked Data JSON (.jsonld) - Quads
* text/trig - TriG (.trig) - Quads
* application/n-quads - N-Quads (.nq) - Quads
* application/trix+xml - TriX (.trix) - Quads
* application/rdf+thrift - Apache Thrift (.trdf) - Quads


## Using with "mm2rdf - Metamodel to RDF"

One of the uses for the meta-model description as RDF (e.g. from the "mm2rdf - Metamodel to RDF" service) is to improve the transformation of models to RDF. For this the meta-model that is provided can be enhanced beforehand by removing statements or adding new statements:
* Ignore certain elements - Remove statements (most notably their rdf:type from the ComVantage namespace) about classes, relations or attributes that should not be transformed in models.
* Attribute defining URL - Specify an attribute to be used to set the URL of model elements in RDF. For this the attribute should be described a subproperty of owl:sameAs in the meta-model (Trig: `rdfs:subPropertyOf owl:sameAs ;`).
* Reference specifying type - Specify an Interref type attribute to be used to denote the rdf:type of model elements in RDF. For this the Interref type attribute should be described as a subproperty of rdf:type (Trig: `rdfs:subPropertyOf rdf:type ;`).
* Direct definition of triples - A table type attribute to be used for specifying explicit RDF triples in the model. For this several changes are necessary:
  - State that the specific table attribute is also of type cv:direct_transformation (Trig: `a cv:direct_transformation ;`, note: this in addition to any other rdf:types).
  - The column of the table that denotes the subject has to be a subproperty of rdf:subject (Trig: `rdfs:subPropertyOf rdf:subject ;`).
  - The column of the table that denotes the predicate has to be a subproperty of rdf:predicate (Trig: `rdfs:subPropertyOf rdf:predicate ;`).
  - The column of the table that denotes the object has to be a subproperty of rdf:object (Trig: `rdfs:subPropertyOf rdf:object ;`).