tabOTTR: Tabular OTTR template instances

top
examples: show / hide

Tabular OTTR template instances (tabOTTR)

Format for representing OTTR template instances using tabular file formats such as CSV, TSV and spreadsheets like MS Excel.

Version: 0.3
Author: Martin G. Skjæveland
Previous versions: https://gitlab.com/ottr/language/tabOTTR/tags
Issues: https://gitlab.com/ottr/language/tabOTTR/issues

This document specifies the format for representing OTTR template instances using tabular file formats such as CSV (with variants, e,g., TSV) and spreadsheets like MS Excel.

tabOTTR is designed to be simple to use and simple to parse. The development is driven by use cases. There are therefore constructs or types of values that may not be possible to represent in tabOTTR. If you come across such cases please let us know by filing an issue where you also provide a compelling case as to why we should support your case.

1 Preliminaries

In order to generalise over different tabular file formats we use here the terms file, table, column, row and cell.

For CSV, we call the entire contents of the file a table, while for spreadsheets, such as in MS Excel files, each sheet in a file represents a table.

Tables, columns and rows within a file have an index which is a positive integer. A cell has a 3-dimensional coordinate: (table, column, row).

Since CSV files only contain a single table, the table index is always 1.

When processing a spreadsheet file all tables in the file are processed.

2 Processing instructions

A table is processed into template instances by directly giving processing instructions in the table using the token #OTTR. This token MUST appear in the first column of the table. The cell to the right of the token MUST contain a processing instruction, with possible instruction arguments given in cells immediately to the right of this cell.

A table can contain multiple processing instructions.

These processing instructions are available:

Instruction name	Number of arguments	1. arg
`end`	0
`prefix`	0
`template`	1	Template IRI

An instruction dictates the syntax and semantics of proceeding rows. The scope of the instruction is all following rows until a row containing a new instruction or until the end of the table.

Rows which are not in scope of an instruction are not processed.

All processed cells are trimmed for leading and trailing whitespace.

All IRIs may be given using a QName, using prefixes set with the prefix instruction.

The following prefixes are implicitly declared for all files:

prefix	namespace
`rdf`	`http://www.w3.org/1999/02/22-rdf-syntax-ns#`
`rdfs`	`http://www.w3.org/2000/01/rdf-schema#`
`owl`	`http://www.w3.org/2002/07/owl#`
`xsd`	`http://www.w3.org/2001/XMLSchema#`
`dc`	`http://purl.org/dc/elements/1.1/`
`ottr`	`http://ns.ottr.xyz/templates#`

2.1 `end` instruction

The end instruction takes no arguments. It is a no-operation instruction whose purpose is to terminate the previous instruction.

We recommend to always use the end instruction to terminate an instruction.

2.2 `prefix` instruction

The prefix instruction takes no arguments. Each following row declares a namespace prefix, where the

1. column must contain the prefix name and the
2. column must contain the namespace name

All other columns are ignored.

Declaring prefixes

This table declares two prefixes: ex and foaf.

`#OTTR`	`prefix`
`ex`	`http://example.net#`
`foaf`	`http://xmlns.com/foaf/0.1/#`
`#OTTR`	`end`

The table is equivalent to the RDF Turtle file given below, which also includes default prefix declarations.

@prefix owl:   <http://www.w3.org/2002/07/owl#> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix ottr:  <http://ns.ottr.xyz/templates#> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dc:    <http://purl.org/dc/elements/1.1/> .

@prefix ex:    <http://example.net#> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/#> .

2.3 `template` instruction

The template instruction takes one argument: an OTTR Template IRI. The immediate next rows have special meaning:

Row +1 MUST for each cell contain a non-negative integer which specifies the template argument index of the columns of the following rows. A column with template argument index 0 specifies that the column will not be processed.
Row +2 MUST specify a type for each template argument column. Permissible values and their interpretation are given below.
Row +3 is ignored. This row can be used for informative content such as column headers.

Each following row (row index > +3) specifies a template instance of the template whose IRI is given by the template instruction. The arguments of the instance are ordered and typed according to respectively rows +2 and +3.

`template` instruction header

The table below contains one template instruction, declaring instances of the http://tlp.ottr.xyz/rdf/Triple template, as prescribed by the first row. The next row select which columns to use as arguments to the template (which takes 3 arguments). Columns with a 0 value will be ignored, and can be, e.g., used for computing values or comments. The next rows sets the tabOTTR type for the columns which will be used as arguments, in this example all columns have the type iri. The next row is ignored and may be used for a descriptive label. The following rows specify instances of the templates.

`#OTTR`	`template`	`http://tlp.ottr.xyz/rdf/Triple`
`1`	`2`	`3`	`0`	`0`
`iri`	`iri`	`iri`	`This is ignored`	`This is ignored too`
`Subject`	`Predicate`	`Object`
…
`#OTTR`	`end`

2.3.1 Data types

Permissible tabOTTR types and their translation to RDF are:

tabOTTR type	RDF type
`iri`	IRI
`blank`	RDF blank node
`text`	untyped RDF literal
an IRI, e.g., an XSD datatype IRI	typed RDF literal
`auto`	individually determined by value, see below
`X+`, where `X` is any of the above tabOTTR types	an RDF list where the type of its list items are determined by the tabOTTR type `X`

Values of an auto typed column are individually typed, meaning the rows of the column may get different RDF types depending on the translation rules given below. The other tabOTTR types specify the type for all the values of the column, hence all values of the column will get the same RDF type.

2.3.2 Value formatting

IRIs are written as either relative or absolute IRIs or a prefixed name using a specified prefix (see the prefix instruction)
Blank nodes, there are two kinds of blank nodes:
- fresh blank nodes are written as the string *
- named blank nodes are specified as for legal RDF blank node labels in the W3C Turtle recommendation: https://www.w3.org/TR/turtle/#BNodes, i.e., roughly the characters _: followed by a non-empty sequence of alphanumeric characters, however the preceding _: may be dropped, i.e., _:name and name represent the same named blank node, assuming the type of the value name is explicitly set to blank. The scope of the named blank node is the entire tabular file.
Typed literals are written using the lexical value and setting their type in the instruction header as specified over; or, if the tabOTTR type is auto, the literal datatype can be set per value by appending the IRI to the value separated by ^^.
Untyped literals are written using their lexical value and setting the argument type to text. An untyped literal may be given a language by appending the language tag to the string separated by @@. The language tag is assumed to consist of only alphanumerical characters and -.
A list is given as a sequence of values separated by $$.
No value. the empty string (after trimming) represent the special no-value value ottr:none. This value has no type.

Formatting values

This example illustrates typing of template instance arguments. We assume that ex is declared as prefix for http://example.net. For each table below we give an equivalent RDF Turtle file (excluding prefix declarations).

IRIs

`#OTTR`	`template`	`ex:Dummy1`
`1`
`iri`
`arg`
`ex:Ann`
`http://example.net#Ann`
`http://other-example.net#Bob`

`Carl`
`#OTTR`	`end`

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ex:Ann ) .

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ex:Ann ) .

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( <http://other-example.net#Bob> ) .

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ottr:none ) . # no value

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( <Carl> ) .    # relative IRI

Blanks

`#OTTR`	`template`	`ex:Dummy1`
`1`
`blank`
`arg`
`*`
`*`
`_:myBlank`
`myBlank`

`_:other`
`#OTTR`	`end`

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( [] ) .        # fresh blank node

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( [] ) .        # fresh blank node

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( _:myBlank ) . # named blank node

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( _:myBlank ) . # same named blank node as above

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ottr:none ) . # no value

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( _:other ) .   # another named blank node

Literals

`#OTTR`	`template`	`ex:Dummy2`
`1`	`2`	`3`	`4`	`5`	`6`
`xsd:int`	`xsd:integer`	`xsd:boolean`	`xsd:string`	`text`	`ex:myDatatype`
`arg`
`9`	`1`	`1`	`1`	`1`	`A`
`123`	`2`	`true`	`a`	`a@@en-GB`	`B`
	`3`	`FALSE`	`true`	`true`	`C`
`#OTTR`	`end`

      ## columns     1               2  3      4                   5          6
[] ottr:templateRef ex:Dummy2;
   ottr:withValues ( "9"^^xsd:int    1  true   "1"^^xsd:string     "1"        "A"^^ex:myDatatype ) .

[] ottr:templateRef ex:Dummy2;
   ottr:withValues ( "123"^^xsd:int  2  true   "a"^^xsd:string     "a"@en-GB  "B"^^ex:myDatatype ) .

[] ottr:templateRef ex:Dummy2;
   ottr:withValues ( ottr:none       3  false  "true"^^xsd:string  "true"     "C"^^ex:myDatatype ) .

Columns 1, 2, 3 and 4 contain "regular" typed literals typed with XSD datatypes. Recall that RDF Turtle does not explicitly type xsd:integers or xsd:booleans. xsd:booleans may be written with any casing and the values 1 and 0.

Column 5 is typed as text which indicates that the arguments are untyped literals. Untyped literals may be given a language with a language tag.

Column 6 is typed with a datatype IRI not in the XSD namespace.

2.3.3 `auto` typing

If a template argument instance argument is typed as auto, each value is individually typed according to following rules:

iri
- if the string is an absolute URL
- if the string is a QName
blank
- if the string starts with _:, it is a named blank node, by which it is assumed to be a legal RDF blank node label
- if the string is *, it is a fresh blank node
typed literal, the following datatypes are supported without explicit typing (for explicit typing, see above):

xsd:boolean
if the string is true, TRUE, false or FALSE

xsd:integer
if the string is an integer number

xsd:decimal
if the string is a decimal number
untyped literal (default), if the string does not match any of the rules above, it is taken to be an untyped literal.

`auto` typed arguments

The table shows how some auto typed values are translated to RDF resources.

`auto` typed value	RDF resource	RDF type
`*`	`[]`	fresh blank node
`_:myBlank`	`_:myBlank`	named blank node
`myBlank`	`"myBlank"`	untyped literal
`ex:Ann`	`ex:Ann`	IRI
`http://other-example#Bob`	`<http://other-example#Bob>`	IRI
`Carl`	`"Carl"`	untyped literal
	`ottr:none`	special none value
`true`	`"true"^^xsd:boolean`	xsd:boolean
`True`	`"True"`	untyped literal
`1`	`"1"^^xsd:integer`	xsd:integer
`-1.2`	`"-1.2"^^xsd:decimal`	xsd:decimal

The example below shows the same values used in a table and an equivalent RDF representation.

`#OTTR`	`template`	`ex:Dummy1`
`1`
`auto`
`arg`
`*`
`_:myBlank`
`myBlank`
`ex:Ann`
`http://other-example#Bob`
`Carl`

`true`
`True`
`1`
`-1.2`
`#OTTR`	`end`

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( [] ) .        # fresh blank node

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( :_myBlank ) .  # fresh blank node

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( "myBlank" ) .  # untyped literal

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ex:Ann ) .     # IRI

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( <http://other-example#Bob> ) . # IRI

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( "Carl" ) .     # untyped literal

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( ottr:none ) .  # no value

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( true ) .    # xsd:boolean

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( "True" ) .  # untyped literal

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( 1 ) .       # xsd:integer

[] ottr:templateRef ex:Dummy1;
   ottr:withValues ( -1.2 ) .    # xsd:decimal

2 triple template instances

The following is a table with 3 columns and 9 rows.

`#OTTR`	`prefix`
`ex`	`http://example.net#`
`#OTTR`	`template`	`http://tlp.ottr.xyz/rdf/Triple`
`1`	`2`	`3`
`iri`	`iri`	`iri`
`Subject`	`Predicate`	`Object`
`ex:Ann`	`rdf:type`	`foaf:Person`
`ex:Bob`	`rdf:type`	`foaf:Person`
`#OTTR`	`end`

The table contains three instructions

a prefix instruction on row 1
a template instruction on row 3
an end instruction on row 9

The prefix instruction declares the prefix ex. This instruction is terminated by the template instruction.

The template instruction specifies 2 template instances of the template http://tlp.ottr.xyz/rdf/Triple.

The file is equivalent to the following RDF turtle graph:

@prefix ex:    <http://example.net#> .
@prefix owl:   <http://www.w3.org/2002/07/owl#> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix ottr:  <http://ns.ottr.xyz/templates#> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dc:    <http://purl.org/dc/elements/1.1/> .

[] ottr:templateRef <http://tlp.ottr.xyz/rdf/Triple> ;
   ottr:withValues ( ex:Ann rdf:type foaf:Person ) .

[] ottr:templateRef <http://tlp.ottr.xyz/rdf/Triple> ;
   ottr:withValues ( ex:Bob rdf:type foaf:Person ) .

2 template instances contd.

The following table specifies the same 2 instances as the previous example:

`#OTTR`	`template`	`http://tlp.ottr.xyz/rdf/Triple`
`2`	`3`	`0`	`1`	`0`
`iri`	`iri`		`iri`
		`ID`	`Name`	`Age`
`rdf:type`	`foaf:Person`	`AB123`	`ex:Ann`	`45`
`rdf:type`	`foaf:Person`	`SV345`	`ex:Bob`	`57`
`#OTTR`	`prefix`
`ex`	`http://example.net#`
`#OTTR`	`end`

The difference between the two tables are that:

The prefix instruction is placed after the template instruction. This is permissible even though the ex prefix is used in the rows preceding the prefix instruction.
The order of the template arguments are changed, however, their template argument index (row 3) is kept.
More columns have been added: Col 3 and Col 5. There are not processed as their template argument index is 0.
Row 4, which is not processed, contains other column headers.

3 Change log

Version 0.3

Change the order of mandatory rows for the template instruction. Issue #10
Change the list item separator to $$. Issue #6
Remove support for preserving leading and trailing space by quoting values.

Version 0.2

First public release.

tabOTTR: Tabular OTTR template instances

Table of Contents

Tabular OTTR template instances (tabOTTR)

1 Preliminaries

2 Processing instructions

2.1 `end` instruction

2.2 `prefix` instruction

Declaring prefixes

2.3 `template` instruction

`template` instruction header

2.3.1 Data types

2.3.2 Value formatting

Formatting values

2.3.3 `auto` typing

`auto` typed arguments

2 triple template instances

2 template instances contd.

3 Change log

4 _footer

Table of Contents

Tabular OTTR template instances (tabOTTR)

1 Preliminaries

2 Processing instructions

2.1 end instruction

2.2 prefix instruction

Declaring prefixes

2.3 template instruction

template instruction header

2.3.1 Data types

2.3.2 Value formatting

Formatting values

2.3.3 auto typing

auto typed arguments

2 triple template instances

2 template instances contd.

3 Change log

4 _footer

2.1 `end` instruction

2.2 `prefix` instruction

2.3 `template` instruction

`template` instruction header

2.3.3 `auto` typing

`auto` typed arguments