Tutorial

In this section we see some use cases of Sheet2RDF and we give examples of spreadsheets and PEARL code. In each of the following tutorials we suppose we're working on a SKOS project. For a better understanding we recommend to read first PEARL documentation.

Working with subject and explicit IDs

This is maybe the simplest use case of Sheet2RDF. In case you want to manually specify the resource ID you can create a sheet with the first column dedicated to the subjects. Since we're working on a SKOSXL project, the subject column should have skos:Concept as header. Let's suppose we just want to assert the broader relation between two concepts: c_2 skos:broader c_1.

Now let's take a look to the PEARL code automatically generated, especially to the nodes section. With this code we're instructing the system to generate subject and col1_node by means of the default CODA converter (uri). This converter generates a URI concatenating the value (in this case col0/value, that is the concept ID, and col1/value) to the end of the base URI.

		 
	prefix	: 	<http://baseuri.org#>
	prefix	coda: 	<http://art.uniroma2.it/coda/contracts/>
	...

	rule it.uniroma2.art.Sheet2RDFAnnotation id:row {
		nodes = {
			subject		uri	col0/value
			col1_node	uri	col1/value
			col2_node 	literal@en col2/value 
		}
		graph = {
			$subject rdf:type skos:Concept .
			OPTIONAL { $subject	skos:broader	$col1_node . }
			OPTIONAL { $subject	skos:prefLabel	$col2_node . }
		}
	}

As stated before, this is the simplest use case of Sheet2RDF, in fact in the related VB tool a spredsheet like the above is immediately resolved: skos:Concept column is considered the subject column (notice the green S badge on the column header), second and third column are linked to valid properties (headers in green), respectively skos:broader and skos:prefLabel as suggested by the same headers' names.

By inspecting the Subject mapping (through the button placed on the spreadsheet preview) you can see how the subject header has been correctly mapped to the first column, the type assertion to skos:Concept and the selection of the default converter (uri).

Moreover the @en suffix on the third column suggests that the values will generate english literals ("en").

The execution of this code generate the following triples. We can note that usinge the default CODA converter, the concept URIs have the local name that is exactly the ID specified under the skos:Concept column.

Working with subject and generated IDs

If we don't want to specify manually the concepts IDs, we can instruct Sheet2RDF to generate them for us. To accomplish this we can define symbolic IDs under the subject column and refer to that from other cells. This IDs are not the same that will be added to the working project, but they will be used by the system to generate the effective random IDs in deterministic mode. As in the previous example, let's create a broader relation between two concepts, but this time we don't specify the effective IDs, we just use some cardinal IDs (1 and 2).

In this case, we have to modify the previous PEARL code, so that the system will generate concepts with random IDs. To accomplish that, we use the randIdGen CODA converter. This converter generates a random URI and assigns it to the subject node. We use the same converter also to the col1_node node that is generated from the value under skos:broader column. Since some values under this column refer to values under the column skos:Concept (e.g. the concept 2 refers to the concept 1 with the property skos:broader), we would like that the randomic IDs generated from both the columns values are generated in a deterministic way, namely 1 under skos:Concept column and 1 under skos:broader column, referring to the same resource, should generate the same URI. In order to accomplish this, we use the @Memoized annotation that ensures that the convertion result is cached and reused when the converter is invoked on the same input.

				 
	...
	nodes = {
		@Memoized
		subject uri(coda:randIdGen('concept')) col0/value .
		@Memoized
		col1_node uri(coda:randIdGen('concept')) col1/value .
		col2_node literal@en col2/value .
	}
	...

As in the previous case, also this spreadsheet is automatically resolved in the VB tool. Anyway we need to perform some changes to the default mapping suggested, otherwise sheet2rdf would generate the same PEARL code seen before (that uses the default uri converter) and it would generate concepts like <http://baseuri.org#1> and <http://baseuri.org#2> (concatenating the baseuri with the cell values).

Through the Subject mapping button we open the Subject Header editor and select the RandomIdGenerator converter. In order to generate IRIs with random local names that match the pattern c_random_part (e.g. c_83f7bc9c) it is suggested to choose the signature with the additional parameter xRole and select the role Concept.
Finally, as explaned before, we need to ensure that the convertion result is cached and reused when the converter is invoked on the same input, so we need to check the Memoize option so that the @Memoized annotation is applied properly.

A similar operation must be done on the skos:broader header. We need to open the header editor and then change the converter selecting the RandomIdGenerator and enabling the Memoize option as before.

As you can see in the following figure, that shows the generated triples, the skos:broader reference points to the correct URI.

Working without subject

Defining symbolic IDs could be a waste of time for someone. As alternative solution we can use the value of some property defined in the sheet as a start for creating the ID without explicit using any column. For example, we can use the label of the concepts and base the references on it. As you can see in this figure, the broader relation of dog points to the label of animal concept.

In this scenario the PEARL code should be modified as follow.

				 
	...
	nodes = {
		@Memoized
		subject uri(coda:randIdGen('concept')) col0/value .
		col0_node literal@en col0/value .
		@Memoized
		col1_node uri(coda:randIdGen('concept')) col1/value .
	}
	...

This time, the subject is generated with randIdGen converter in combination with the @Memoized annotation (as in the previous case) but starting from the col0_skos_prefLabel_en/value. As already state in the previous example, if we want to make reference to that subject in other row, we have to use the same converter (as for col1_skos_broader/value).

Unlike the previous examples, in this case the VB tool is not able to automatically detect the subject column (notice Subject mapping in red), so we need to instruct Sheet2RDF.

Clicking on the same button the Subject Header editor is prompted where we can map the subject to the header skos:prefLabel@en (first column), eventually assert the type to skos:Concept, select the RandomIdGenerator converter and enabling the Memoize option.

Similar changes must be done also to the skos:broader header as already shown in the previous example.

As we expected, the references in the following generated triples are correct.

If we are not interested to make references between resources, we could omit the @Memoized annotation and let the randomic converter generate a new random ID at each invocation. More about the available converters is here.

-->