Tutorial: Get started with Target in RML

Table of Contents

• 1 Before we start the tutorial
  • 1.1 What you learn
  • 1.2 What you need
  • 1.3 How you use the tutorial
• 2 Example
• 3 What rules are needed
• 4 How to start a document with RML and Target rules
• 5 How to define a Target
• 6 How to integrate Target with RML
• 7 How to specify multiple Targets
• 8 Complete Turtle document with RML and Target rules
• 9 Wrapping up
• 10 More information

1 Before we start the tutorial

1.1 What you learn

At the end of the tutorial you will be able to export your generated RDF with RML to various targets using Target.

1.2 What you need

We assume that you understand

• RDF
• RML
• vocabularies and ontologies, such as classes, properties, and datatypes

1.3 How you use the tutorial

There are two ways to complete this tutorial: you read the explanations and either

• Read the examples.
• Try out the examples yourself by writing and executing RML and Target rules on your computer.

For the second option you need a tool that executes RML and Target rules. Suggestions are the RMLMapper and the RMLStreamer.

2 Example

Note: This tutorial builds upon the example of the Generate RDF from a JSON file with RML, if you haven't read that tutorial, you can find it here.

Consider the following JSON file called "characters.json":

{
 "characters": [
   {
     "id": "0",
     "firstname": "Ash",
     "lastname": "Ketchum",
     "hair": "black"
   },
   {
     "id": "1",
     "firstname": "Misty",
     "hair": "orange"
   }
 ]
}

And the RML rules to generate RDF from this JSON file:

@prefix rml: <http://semweb.mmlab.be/ns/rml#> .
@prefix rr: <http://www.w3.org/ns/r2rml#> .
@prefix ql: <http://semweb.mmlab.be/ns/ql#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <http://example.org/rules/> .
@prefix schema: <http://schema.org/> .
@prefix dbo: <http://dbpedia.org/ontology/> .

:TriplesMap a rr:TriplesMap;
  rml:logicalSource [
    rml:source "characters.json";
    rml:referenceFormulation ql:JSONPath;
    rml:iterator "$.characters[*]"
  ].

:TriplesMap rr:subjectMap [
  rr:template "http://example.org/character/{id}"
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate rdf:type;
  rr:objectMap [
   rr:constant schema:Person
 ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate schema:givenName;
  rr:objectMap [
    rml:reference "firstname"
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate schema:lastName;
  rr:objectMap [
    rml:reference "lastname"
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate dbo:hairColor;
  rr:objectMap [
    rml:reference "hair"
  ]
].

These RML rules generate the following RDF:

@prefix schema: <http://schema.org/> .
@prefix dbo: <http://dbpedia.org/ontology/> .
@prefix character: <http://example.org/character/> .

character:0 a schema:Person;
  schema:givenName "Ash";
  schema:lastName "Ketchum";
  dbo:hairColor "black".

character:1 a schema:Person;
  schema:givenName "Misty";
  dbo:hairColor "orange".

We want to export the generated RDF to a local file, with JSON-LD as serialization and GZip compression.

In the following sections we explain

1. how you define a Target.
2. how you combine RML and Target to export your RDF.

3 What rules are needed

Two sets of rules are needed:

• rules that describe how the RDF is generated.
• rules that describe how the generated RDF is exported to one or multiple targets.

In our example we need rules that define that:

• The generation of RDF from a JSON file, which is explained here.
• The target location to where the RDF is exported.
• The serialization format for the target.
• If needed, the compression algorithm for compressing the RDF.

4 How to start a document with RML and Logical Target rules

We write the RML and Target rules in a Turtle document. RML and Target rules are RDF themselves.

We add the following prefixes:

Prefix	Description
rml	RML ontology
rmlt	Target ontology
comp	Compression algorithms namespace, which is used together with Target
formats	W3C formats namespace, which is used together with Target
void	The Void ontology, which is used as an access description in Target
rr	The R2RML ontology, which is extended by RML
ql	The Query Language vocabulary, which is used together with RML
rdf	The RDF Concepts Vocabulary
empty	The prefix used for our RML rules
schema	The schema.org vocabulary
dbo	The DBpedia ontology

The last two are added because they are used for the classes and properties.

The prefixes are added in Turtle like this:

@prefix rml: <http://semweb.mmlab.be/ns/rml#> .
@prefix rmlt: <http://semweb.mmlab.be/ns/rml-target#> .
@prefix comp: <http://semweb.mmlab.be/ns/rml-compression#> .
@prefix formats: <https://www.w3.org/ns/formats/> .
@prefix void: <http://rdfs.org/ns/void#> .
@prefix rr: <http://www.w3.org/ns/r2rml#> .
@prefix ql: <http://semweb.mmlab.be/ns/ql#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <http://example.org/rules/> .
@prefix schema: <http://schema.org/> .
@prefix dbo: <http://dbpedia.org/ontology/> .

5 How to define a Target

In our example, we want to export our generated RDF to a local file, with JSON-LD serialization and GZip compression. We add the following Target rules that define to where the generated RDF is exported, in which serialization and which compression algorithm must be used:

:Target1 a rmlt:LogicalTarget;
  rmlt:target [ a void:Dataset;
    void:dataDump <file://dump.jsonld.gz>;
  ]; 
  rmlt:serialization formats:JSON-LD;
  rmlt:compression comp:gzip;
.

The different rules work as follows:

• :Target a rmlt:LogicalTarget; defines the Target to where the generated RDF is exported.
• The blank node of :Target rmlt:target [ ... ] contains all rules to access the Target location.
• [rmlt:serialization formats:JSON-LD] says that we want to use JSON-LD as RDF serialization format for this Target.
• [rmlt:compression comp:gzip] says that we want GZip as compression.

Note: You can not only use a file as Target, but also a SPARQL endpoint or other Targets. You can find more examples in the DataIO specifcation.

6 How to integrate Target with RML

Target is aligned with RML through rml:logicalTarget property in a RML Term Map. A Term Map can be a Subject Map, Predicate Map, Object Map, Graph Map or Language Map. Assume we have the following RML and Target rules:

:TriplesMap rr:predicateObjectMap [
  rr:predicate schema:givenName;
  rr:objectMap [
    rml:logicalTarget :Target;
    rml:reference "firstname";
  ]
].

We will only focus on rml:logicalTarget, the other rules are explained here. In this example, we export all triples which contain the object generated by the Object Map to a specific Target.

Note: If no Target is specified for a triple, it is exported to the default Target of the processor. The default Target is processor-specific.

7 How to specify multiple Targets

You can also add multiple rml:logicalTarget properties to RML rules. This way, you can export your generated RDF to multiple Targets directly:

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant schema:givenName;
  ];
  rr:objectMap [
    rml:logicalTarget :Target1;
    rml:logicalTarget :Target2;
    rml:reference "firstname";
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant schema:lastname;
  ];
  rr:objectMap [
    rml:logicalTarget :Target3;
    rml:reference "lastname";
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant dbo:hairColor;
  ];
  rr:objectMap [
    rml:reference "hair";
  ]
].

If these rules are executed by an RML and Target processor, the generated triples are exported as followed:

• Target1 and Target2: All triples containing the predicate schema:givenName are exported to both Targets.
• Target3: All triples containing the object from the "lastname" reference are exported to Target3 only.
• Default Target: All triples about the hair color (predicate: dbo:hairColor and object "hair" reference) do not have any Target assigned, they are exported to the default Target of the processor.

If you put all these rules together, you get following Turtle document:

@prefix rml: <http://semweb.mmlab.be/ns/rml#> .
@prefix rmlt: <http://semweb.mmlab.be/ns/rml-target#> .
@prefix comp: <http://semweb.mmlab.be/ns/rml-compression#> .
@prefix formats: <https://www.w3.org/ns/formats/> .
@prefix void: <http://rdfs.org/ns/void#> .
@prefix rr: <http://www.w3.org/ns/r2rml#> .
@prefix ql: <http://semweb.mmlab.be/ns/ql#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <http://example.org/rules/> .
@prefix schema: <http://schema.org/> .
@prefix dbo: <http://dbpedia.org/ontology/> .

:Target1 a rmlt:LogicalTarget;
  rmlt:target [ a void:Dataset;
    void:dataDump <file://dump1.jsonld.gz>;
  ]; 
  rmlt:serialization formats:JSON-LD;
  rmlt:compression comp:gzip;
.

:Target2 a rmlt:LogicalTarget;
  rmlt:target [ a void:Dataset;
    void:dataDump <file://dump2.ttl>;
  ]; 
  rmlt:serialization formats:Turtle;
.

:Target3 a rmlt:LogicalTarget;
  rmlt:target [ a void:Dataset;
    void:dataDump <file://dump3.nq>;
  ]; 
  rmlt:serialization formats:N-Quads;
.

:TriplesMap a rr:TriplesMap;
  rml:logicalSource [
    rml:source "characters.json";
    rml:referenceFormulation ql:JSONPath;
    rml:iterator "$.characters[*]"
  ].

:TriplesMap rr:subjectMap [
  rr:template "http://example.org/character/{id}"
].

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant schema:givenName;
  ];
  rr:objectMap [
    rml:logicalTarget :Target1;
    rml:logicalTarget :Target2;
    rml:reference "firstname";
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant schema:lastname;
  ];
  rr:objectMap [
    rml:logicalTarget :Target3;
    rml:reference "lastname";
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicateMap [
    rr:constant dbo:hairColor;
  ];
  rr:objectMap [
    rml:reference "hair";
  ]
].

These rules generate our RDF and they are exported to four different targets:

# Default target: N-Quads to stdout
<http://example.org/character/0> <http://dbpedia.org/ontology/hairColor> "black".
<http://example.org/character/1> <http://dbpedia.org/ontology/hairColor> "orange".

# Target1: JSON-LD file with GZip compression (shown decompressed)
[ {
  "@id" : "http://example.org/character/0",
  "http://schema.org/givenName" : [ {
    "@value" : "Ash"
  } ]
}, {
  "@id" : "http://example.org/character/1",
  "http://schema.org/givenName" : [ {
    "@value" : "Misty"
  } ]
} ]

# Target2: Turtle file
<http://example.org/character/0> <http://schema.org/givenName> "Ash" .
<http://example.org/character/1> <http://schema.org/givenName> "Misty" .

# Target3: N-Quads file
<http://example.org/character/0> <http://schema.org/lastname> "Ketchum" .

You can download the rules here.

8 Complete Turtle document with RML and Target rules

The complete Turtle document with RML and Target rules with a single target is:

@prefix rml: <http://semweb.mmlab.be/ns/rml#> .
@prefix rmlt: <http://semweb.mmlab.be/ns/rml-target#> .
@prefix comp: <http://semweb.mmlab.be/ns/rml-compression#> .
@prefix formats: <https://www.w3.org/ns/formats/> .
@prefix void: <http://rdfs.org/ns/void#> .
@prefix rr: <http://www.w3.org/ns/r2rml#> .
@prefix ql: <http://semweb.mmlab.be/ns/ql#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <http://example.org/rules/> .
@prefix schema: <http://schema.org/> .
@prefix dbo: <http://dbpedia.org/ontology/> .

:Target1 a rmlt:LogicalTarget;
  rmlt:target [ a void:Dataset;
    void:dataDump <file://dump.jsonld.gz>;
  ]; 
  rmlt:serialization formats:JSON-LD;
  rmlt:compression comp:gzip;
.

:TriplesMap a rr:TriplesMap;
  rml:logicalSource [
    rml:source "characters.json";
    rml:referenceFormulation ql:JSONPath;
    rml:iterator "$.characters[*]"
  ].

:TriplesMap rr:subjectMap [
  rr:template "http://example.org/character/{id}"
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate rdf:type;
  rr:objectMap [
   rr:constant schema:Person
 ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate schema:givenName;
  rr:objectMap [
    rml:logicalTarget :Target1;
    rml:reference "firstname"
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate schema:lastName;
  rr:objectMap [
    rml:reference "lastname"
  ]
].

:TriplesMap rr:predicateObjectMap [
  rr:predicate dbo:hairColor;
  rr:objectMap [
    rml:reference "hair"
  ]
].

You can download the Turtle file here. If we execute these rules, the final triples are generated:

# Default target: N-Quads to stdout
<http://example.org/character/0> <http://dbpedia.org/ontology/hairColor> "black".
<http://example.org/character/0> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person>.
<http://example.org/character/0> <http://schema.org/lastName> "Ketchum".
<http://example.org/character/1> <http://dbpedia.org/ontology/hairColor> "orange".
<http://example.org/character/1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person>.
  
# Target1: JSON-LD file with GZip compression (shown decompressed)
[ {
  "@id" : "http://example.org/character/0",
  "http://schema.org/givenName" : [ {
    "@value" : "Ash"
  } ]
}, {
  "@id" : "http://example.org/character/1",
  "http://schema.org/givenName" : [ {
    "@value" : "Misty"
  } ]
} ]

9 Wrapping up

Congratulations! You have created your own Target rules that generate RDF from data in a JSON file and export the RDF as JSON-LD to a local file with GZip compression. Nice work! We hope you now feel like you have a decent grasp on how Target rules work.

10 More information

You can find more information about Target in the DataIO specification and how Target is aligned with RML in the Target in RML specification.

If you have questions or remarks, don't hesitate to contact us via email!