General

What to do if my platform does not support semantics?

If a platform that wants to join the ecosystem of interconnected IoT artifacts does not support semantics, it still can be integrated. To achieve interoperability at data and semantics layer the message leaving the INTER-MW bridge component (or INTER-AS2AS converter node) needs to be in INTER-IoT JSON-LD format. To transform any other format into JSON-LD a syntactic translator has to be implemented and applied. In a nutshell, it is responsible for creating RDF graph named payload and mapping original message content onto proposed RDF structure. Note that in simple cases, it is not necessary to design an ontology for platforms not supporting semantics but only RDF graph structure that will be send in the message and from which the alignment to central ontology can be defined. More information about syntactic translators in INTER-MW is available here.

How do you analyse data models, matches, and set the alignments between them?

Here, any tool for viewing data models in different format can be used e.g. XSD viewer, database client. For OWL ontology we recommend Protege . For translation between different RDF syntaxes you can use RDF Translator. For JSON-LD structure visualization use JSON-LD Playground.

The paper outlines tools and approaches that can be used to match ontologies and eventually create alignments.

How do you test an alignment?

The best way to test the alignment is to use IPSM Dashboard. It allows to test the alignment on a single message to verify if the output is as expected. The good practice when testing an alignment is to check the output RDF graph after application of each cell. To limit cells that should be applied comment respective elements of sripas:step.

Besides IPSM Dashboard a REST API with translate operation can be used. In both, cases, user can apply a sequence of selected alignments to transform the input RDF graph.

How do you find the patterns that have to be changed in the translation?

This requires investigation and knowledge of source and target data formats. To help with finding potential common entities between ontologies (or other formats) one of the matching tools can be used.

How do I set up translation for data coming from platform already connected to the platforms' ecosystem?

In a typical deployment in an ecosystem of interconnected platforms, a central ontology is used. Central ontology provides a common understanding (semantics) of messages exchanged in the system. It should model the knowledge that is persisted in the message content. To connect a new platform, first, parts of the data model that will be shared with third parties need to be determined. These parts need to be mapped onto central ontology and alignment needs to be created. If communication is one directional then only one alignment needs to be created - from platform's semantics to central ontology or from central ontology to platform's semantics. If communication will be two directional then two alignments need to be defined - to and from platform's semantics to central ontology.

Alignments

How to translate a RDF triple?

In IPSM-AF cell the simplest type of operation is a translation of RDF triple.

Namespaces Suggested prefix
http://www.inter-iot.eu/sripas# sripas
http://www.inter-iot.eu/sripas:node_ var
http://www.inter-iot.eu/sripas:pred_ pred 
<align:Cell rdf:about="2_entry_vehicle_clear">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <ont1:hasName>
                <var:CTY/>                        
            </ont1:hasName>
        </var:CTX>
    </align:entity1>    
    <align:entity2 rdf:parseType="Literal">
        <var:CTX>
            <ont2:hasVorname>
                <var:CTY/>                        
            </ont2:hasVorname>
        </var:CTX>
    </align:entity2>
    <align:relation>=</align:relation>
</align:Cell>

How to translate between URIs (rename)?

In IPSM-AF align:entity1 and align:entity2 contain RDF patterns in the form of RDF triples (in XML/RDF or Turtle syntax). Therefore, to rename an entity i.e. translate it's URI, a triple pattern needs to be used. The only part that is different is the object in each triple.

RDF/XML syntax:

<align:map><align:Cell rdf:about="http://www.inter-iot.eu/sripas#Cell_1">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="&sosa;Observation" />
            <sosa:hasResult>
                <rdf:Description rdf:about="http://platform1/temp/res1"/>
            </sosa:hasResult>
        </var:CTX>
    </align:entity1>
    <align:entity2 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="&sosa;Observation" />
            <sosa:hasResult>
                <rdf:Description rdf:about="http:/platform1/temperature/res1"/>
            </sosa:hasResult>
        </var:CTX>
    </align:entity2>
    <align:relation>=</align:relation>
</align:Cell></align:map>

Turtle sytnax:

<align:map><align:Cell rdf:about="http://www.inter-iot.eu/sripas#Cell_1">
    <align:entity1 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
        var CTX a sosa:Observation ;
        sosa:hasResult ont1:res1 .
    </align:entity1>
    <align:entity2 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
        var CTX a sosa:Observation ;
        sosa:hasResult ont2:res1 .
    </align:entity2>
    <align:relation>=</align:relation>
</align:Cell></align:map>

How to create a new named entity?

In order to create a named entity a IRI function has to be used that constructs an IRI by resolving the string argument.

RDF/XML:

<align:map><align:Cell rdf:about="http://www.inter-iot.eu/sripas#Cell 1">
    <align:entity1 rdf:parseType="Literal">
        <var:elem>
            <rdf:type rdf:resource="&pt;Elem" />
            <pt:hasDeviceId><var:device_id/></pt:hasDeviceId>
        </var:elem/>
    </align:entity1>
    <align:entity2 rdf:parseType="Literal">
        <var:device>
            <rdf:type rdf:resource="&iiot;Device" />
            <rdf:type rdf:resource="&sosa;Sensor" />
            <iiotex:hasLocalId var:device_id/>
        </var:device>
    </align:entity2>
    <align:relation>=</align:relation>
    <sripas:transformation rdf:parseType="Literal">
        <function about="IRI">
            <param order="1" about="&var;device_id"/>
            <return about="&var;device"/>
        </function>
    </sripas:transformation>
</align:Cell></align:map>

Turtle:

<align:map><align:Cell rdf:about="http://www.inter-iot.eu/sripas#Cell 1">
    <align:entity1 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
        var:elem a pt:Element ;
        pt:hasdeviceId var:device_id .
    </align:entity1>
    <align:entity2 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
        var:device a iiot:IoTDevice, sosa:Sensor ;
        iiotex:hasLocalId var:device_id .
    </align:entity2>
    <align:relation>=</align:relation>
    <sripas:transformation rdf:parseType="Literal">
        <function about="IRI">
            <param order="1" about="&var;device_id"/>
            <return about="&var;device"/>
        </function>
    </sripas:transformation>
</align:Cell></align:map>

How to generate blank node?

To add blank node to the target RDF graph a rdf:Description element should be used. The following example shows how blank nodes are included in the output RDF graph to generate structure supported by W3C Time Ontology.

<align:map><align:Cell rdf:about="http://www.inter-iot.eu/sripas#Cell_1">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="&sosa;Observation" />
            <S2:hasMsgTimestamp>
                <sripas:node_timestamp/>
            </S2:hasMsgTimestamp>
        </var:CTX>
    </align:entity1>
    <align:entity2 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="&sosa;Observation" />
                <sosa:phenomenonTime>
                    <rdf:Description>
                        <rdf:type rdf:resource="&time;Instant" />
                        <time:inPosition>
                            <rdf:Description>
                                <rdf:type rdf:resource="&time;TimePosition" />
                                <time:nominalPosition>
                                    <sripas:node_timestamp/>
                                </time:nominalPosition>
                            </rdf:Description>
                        </time:inPosition>
                    </rdf:Description>
                </sosa:phenomenonTime>
        </var:CTX>
    </align:entity2>
    <align:relation>=</align:relation>
</align:Cell></align:map>

How to remove triples from RDF graph?

In order to remove triple from an RDF graph it has to be declared in IPSM-AF align:entity1 and omitted in align:entity2. Analogically, entity type declaration can be removed. The following example shows how to remove ont1:hasName property for var:CTX entity.

<align:Cell rdf:about="2_entry_vehicle_clear">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <ont1:hasName>
                <var:CTY/>                        
            </ont1:hasName>
        </var:CTX>
    </entity1>  
    <entity2 rdf:parseType="Literal">
    </entity2>
    <relation>=</relation>
</Cell>

The following example shows how to erase type declaration.

<align:Cell rdf:about="2_entry_vehicle_clear">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="http://www.w3.org/ns/sosa/Result"/>
        </var:CTX>
    </entity1>  
    <entity2 rdf:parseType="Literal">
    </entity2>
    <relation>=</relation>
</Cell>

To change the type of entity use:

<align:Cell rdf:about="2_entry_vehicle_clear">
    <align:entity1 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="http://www.w3.org/ns/sosa/Result"/>
        </var:CTX>
    </entity1>  
    <entity2 rdf:parseType="Literal">
        <var:CTX>
            <rdf:type rdf:resource="https://w3id.org/saref#Measurement"/>
        </var:CTX>
    </entity2>
    <relation>=</relation>
</Cell>

How to use a function in the alignment?

To call a function from an alignment cell transformation use sripas:function element. The following example shows how the syntax looks like:

<sripas:transformation rdf:parseType="Literal">
    <sripas:function sripas:about="str">
        <sripas:param sripas:order="1" sripas:about="http://www.inter-iot.eu/sripas#node_xy"/>
        <sripas:return sripas:about="http://www.inter-iot.eu/sripas#node_sxy"/>
    </sripas:function>
    <sripas:function sripas:about="replace">
        <sripas:param sripas:order="1" sripas:about="http://www.inter-iot.eu/sripas#node_sxy"/>
        <sripas:param sripas:order="2" sripas:val="^Point\\((\\d+\\.\\d+)\\s+\\d+\\.\\d+\\)$"/>
        <sripas:param sripas:order="3" sripas:val="$1"/>
        <sripas:param sripas:order="4" sripas:val="i"/>
        <sripas:return sripas:about="http://www.inter-iot.eu/sripas#node_x"/>
    </sripas:function>
    <sripas:function sripas:about="replace">
        <sripas:param sripas:order="1" sripas:about="http://www.inter-iot.eu/sripas#node_sxy"/>
        <sripas:param sripas:order="2" sripas:val="^Point\\(\\d+\\.\\d+\\s+(\\d+\\.\\d+)\\)$"/>
        <sripas:param sripas:order="3" sripas:val="$1"/>
        <sripas:return sripas:about="http://www.inter-iot.eu/sripas#node_y"/>
    </sripas:function>
</sripas:transformation>

In this sample alignment cell three function call are made. STR takes as input value of variable var:xy from align:entity1. The result is stored in a variable var:sxy. Then two REPLACE functions are called with input parameter being var:sxy (output of STR function call). Additional parameters are also provide for the function call. Inside sripas:function there are: sripas:param and sripas:return elements for representing, respectively, parameters of the function and value returned by the function. sripas:order attribute determine the order in which arguments should be passed to the function. Attribute sripas:about is for indicating variables (or instances) and sripas:val is for passing simple values. Value returned by the function is always stored in a variable that can be later used in another function call or align:entity2 of the alignment cell.

Available functions are referenced here.

Where can I find sample alignments?

In INTER-IoT Git repository sample alignments are available that can be used as an example.

Debugging

What if messages are not translated?

If messages that are published to IPSM translation channel input topic are not translated at the output, then you can:

  1. Go to IPSM Dashboard monitoring page and turn on channel monitoring
  2. Send message to channel that is monitored
  3. Use Translation tab in IPSM Dashboard to translate the message with a selected alignment
  4. Check the translated message preview if the message was translated
  5. Modify the input message to verify how it beheaves

Dashboard monitoring and then REST based translation.