bOTTR: Batch instantiation of OTTR templates
top
examples:
/
Table of Contents
Batch Instantiation of OTTR templates (bOTTR)

An Extract-Transform-Load (ETL) mapping language for instantantiating OTTR templates from existing external sources.
- Version
- 0.1.2
- Published
Tue Feb 7 13:51:05 2023
- Authors
- Martin G. Skjæveland
- Issues
- https://gitlab.com/ottr/language/bOTTR/issues
1 Introduction
This specification defines bOTTR, a language for specifying mappings between queries over the sources to given templates. bOTTR hence allows multiple data sources on different formats to be integrated via OTTR templates into a single RDF/OWL representation.
The vocabulary of the bOTTR language is specified by an OWL ontology which extends the wOTTR [2] ontology.
1.1 Documents
This specification consists of the following files:
- ./core-vocabulary.owl.ttl
- Ontology declaring the core vocabulary of bOTTR.
- ./index.html
- This file.
1.2 Document conventions
1.2.1 Notation
This is a defined term.
This is a mention of a defined term.
This is an example box. Examples are informative.
Examples are standalone and makes no reference to external resources unless explicitly stated. The examples are meant to illustrate use of the syntax, and not necessarily to display interesting or useful templates.
1.2.2 Prefixes
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix owl: <http://www.w3.org/2002/07/owl#> . @prefix skos: <http://www.w3.org/2004/02/skos/core#> . @prefix vann: <http://purl.org/vocab/vann/> . @prefix dc: <http://purl.org/dc/elements/1.1/> . @prefix foaf: <http://xmlns.com/foaf/0.1/> . @prefix dcterms: <http://purl.org/dc/terms/> . @prefix cc: <http://creativecommons.org/ns#> . @prefix sh: <http://www.w3.org/ns/shacl#> . @prefix dash: <http://datashapes.org/dash#> . @prefix ex: <http://example.net/ns#> . @prefix ottr: <http://ns.ottr.xyz/0.4/> . @prefix o-wottr: <http://spec.ottr.xyz/wOTTR/0.4.4/tpl/> . @prefix o-bottr: <http://spec.ottr.xyz/bOTTR/0.1.2/tpl/> .
1.2.3 Diagrams
The diagrams in this document are informal, but should be understood in the following way:
- Arrows with open heads indicate subclass relationships—pointing to the superclass
- Dotted arrows indicate type relationships—pointing to the class
- Other arrows indicate domain and possibly range restrictions to
properties—pointing from the domain (arrow source) to the
range (arrow target):
- A regular arrowhead indicates a regular domain and range restriction
- A pink target indicates that the range is a literal of the given type. The name of the relation is given by the target node.
- A green target indicates a non-literal range.
- An empty blue target indicates that the range is unspecified, i.e., it can be either literal or non-literal or both.
- A diamond arrowhead indicates that the range is a list of the target class

1.3 Changelog
- 0.1.2
- Added
ottr:fetchSize
.
2 bOTTR language
In order make the presentation more readable, we will frequently
write, "a Class
", e.g., "a ottr:InstanceMap
", and take this to mean
a resource of type ottr:InstanceMap
. Also, we will write, e.g., "a
ClassX
has a property
which is a ClassY
" and take this to mean
that there must be a triple (x, property
, y), where x has
the type ClassX
and y has the type ClassY
, e.g., "a
ottr:Source
has a ottr:query
which is an XSD string". The
type information need not be explicitly stated, but can be inferred.
2.1 Overview
The bOTTR vocabulary extends the wOTTR [2] vocabulary, and provides a vocabulary for specifying sources, queries over these sources, and how to map the query results into instances of a specified OTTR template.
The classes ottr:InstanceMap
, ottr:Source
and its subclasses,
and ottr:ArgumentMap
, which specify respectively the mappings,
the source and the translation of source values to template
instance arguments, are described below.
A complete schematic overview of the ontology is given in Figure 2.

2.2 InstanceMap
The central notional of bOTTR is ottr:InstanceMap
. An
ottr:InstanceMap
specifies a mapping between one ottr:query
over a given ottr:Source
and one ottr:Template
. The result of
applying the mapping is that each record in the query result set
becomes an ottr:Instance
of the specified ottr:Template
. The
ottr:argumentMaps
specify how source values are translated to
instance arguments.
An ottr:InstanceMap
must specify
- a
ottr:template
, which must beottr:Signature
[2], - a
ottr:source
, which must be aottr:Source
, - a
ottr:query
, which must axsd:string
and a valid query over the specifiedottr:Source
, and - optionally a list of
ottr:argumentMaps
. If set, the size of the argument map list must match the size of the query result records.
The result of processing a set of ottr:InstanceMap
-s is the set
of instances resulting from each of the ottr:InstanceMap
-s.

2.3 Sources
A ottr:Source
defines a source and how it can be accessed. The
location of the source is specified with ottr:sourceURL
, this can
be either a URL or a file path.
There are two main types of ottr:Sources
: ottr:StringSource
and
ottr:RDFSource
. These source types again have subclasses.
All source values from a ottr:StringSource
is
assumed to be a string, and if no ottr:argumentMaps
are set, then
these source values are represented as untyped literals when
transforming them to instance arguments. No assumption is made on
the type of the ottr:query
, this must be specified by using a
subclass of ottr:StringSource
.
For a ottr:RDFSource
, all values are assumed to be RDF
resources. If no ottr:argumentMaps
are set then the values left
as they are when used as instance arguments. An ottr:RDFSource
accepts only SPARQL queries.

In the following example we assume that ex:rdfSource
is a valid RDF
source. Then this ottr:InstanceMap
specifies a mapping using a
SPARQL query over the source which creates 10 instances of the
ottr:Triple
template.
[] a ottr:InstanceMap ; ottr:source ex:rdfSource ; ottr:query """ SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10 """; ottr:template ottr:Triple .
2.3.1 RDFFileSource
An ottr:RDFFileSource
is an ottr:RDFSource
which is specified
by a non-empty set of RDF files, i.e,. files assumed to contain
valid RDF graphs. The files are set using ottr:sourceURL
. The
source is the union of the RDF graphs contained in these files.
This is a valid specification of a ottr:RDFFileSource
.
[] a ottr:RDFFileSource ; ottr:sourceURL <http://example.com/file1.ttl>, <http://example.com/file2.ttl> .
2.3.2 SPARQLEndpointSource
A ottr:SPARQLEndpointSource
is an ottr:RDFSource
which is
specified by a single SPARQL endpoint address using ottr:sourceURL
.
This is a valid specification of a ottr:SPARQLEndpointSource
.
[] a ottr:SPARQLEndpointSource ; ottr:sourceURL <http://example.com/sparql/> .
2.3.3 JDBCSource
A ottr:JDBCSource
is a ottr:StringSource
which represents a
database accessed by a JDBC connection.
A ottr:JDBCSource
may specify these properties:
ottr:sourceURL
:xsd:string
, the url to the database,ottr:jdbcDriver
:xsd:string
, the JDBC driver class of the database,ottr:username
xsd:string
, the username and …ottr:password
:xsd:string
, password to use for connecting to the database,ottr:fetchSize
:xsd:integer
, the desired number of rows retrieved from the database on each fetch from the database (if set, the value is put directly into JDBC's Statement::setFetchSize, otherwise no such call is made and the driver's default is used)
This is a valid specification of a ottr:JDBCSource
.
[] a ottr:JDBCSource ; ottr:sourceURL "jdbc:mysql://localhost/mydb" ; ottr:jdbcDriver "com.mysql.jdbc.Driver" ; ottr:username "Ann" ; ottr:password "password123" .
2.3.4 H2Source: SQL over CSV files
An ottr:H2Source
is a ottr:StringSource
which is useful for
querying with SQL over value separated formats such as CSV and
TSV.
An ottr:H2Source
is specified without any properties. This results
in a new and empty H2 database created in a temporary location of
the file system. The H2 database system supports loading different
value separated file into the database with CSVREAD
, see the
documentation:
http://www.h2database.com/html/functions.html#csvread.
To make the path to the file accessed with CSVREAD
(or other
functions in the query) relative to the file containing the bOTTR
mapping, use the token @@THIS_DIR@@
. This token will be replaced
by the absolute path of the folder of the mapping file.
This is an instance map that maps an SQL query over the file
address.csv
to instances of the ex:Person
template. Note that the
ottr:H2Source
is specified without any properties.
[] a ottr:InstanceMap ; ottr:source [ a ottr:H2Source ] ; ottr:query """ SELECT 'First Name', 'Age', 'Homepage' FROM CSVREAD('@@THIS_DIR@@/address.csv'); """ ; ottr:template ex:Person .
The file address.csv
is located in the same folder as the file
containing the instance map, and assuming that the contents of
address.csv
are as follows:
First Name | Last Name | Age | City | Homepage |
---|---|---|---|---|
Ann | Annsen | 30 | Amsterdam | http://example.com/Ann |
Bob | Bobson | 31 | Berlin | http://example.com/Bob |
Carl | Carlson | 32 | Cairo | http://example.com/Carl |
then the instance map will produce the following instances, here shown in stOTTR [3] format:
ex:Person ("Ann", "30", "http://example.com/Ann" ) . ex:Person ("Bob", "31", "http://example.com/Bob" ) . ex:Person ("Carl", "32", "http://example.com/Carl" ) .
Note that, since the instance map does not specify :argumentMaps
,
all values are treated as strings, as ottr:H2Source
is a
ottr:StringSource
. We will see in a later example how to produce
other types of values.
Note that it is also possible to connect to a H2 database source using
ottr:JDBCSource
.
2.4 ArgumentMap
An ottr:ArgumentMap
specifies how source values are mapped to OTTR
template instance arguments, i.e., RDF terms. In case no argument maps
are specified, defaults apply from the choice of ottr:Source
, see
2.3.

When applying an argument map to source value, we sometimes refer to
the string value of the source value. In case the source is a
ottr:StringSource
, then the string value of a source value x is
x. In case the source is an ottr:RDFSource
, the string value is of
an RDF resource x is:
- the lexical value of x, if x is a literal
- the IRI of x, if x is a IRI,
- the blank node label of x, if x is a blank node
An ottr:ArgumentMap
is defined by the following properties:
ottr:type
- Specifies the
ottr:Type
[2] of the argument value. If the source is anottr:RDFSource
and the type of the source value is compatible [1] with the specifiedottr:type
, then the argument value is equal to the source value (the argument map leaves the value unchanged). If the value is not compatible or the source is aottr:StringSource
, then the string value of the source value is cast to the specifiedottr:type
. This may result in an error if the cast not possible. ottr:nullValue
- Specifies the argument value to be used in case
the source value is unspecified or
NULL
. This value may be any RDF resource, and may be specified for all values ofottr:type
. ottr:labelledBlankPrefix
- Selects which values to translate to labelled blank nodes. The
default value is
_:
. If the string value of the source value starts with and is longer than theottr:labelledBlankPrefix
, then the argument value becomes a labelled blank node where the sting value of the source value following theottr:labelledBlankPrefix
becomes the label. Example: if theottr:labelledBlankPrefix
is"ABC"
and the source value is"ABCDEF"
, then a labelled blank node_:DEF
is created. This property may be specified for all values ofottr:type
. ottr:languageLag
- Specifies the language tag of the argument value. If this value is set, then the source value becomes an language tagged literal where the lexical value is the string value of the source value.
ottr:listStart
,ottr:listEnd
,ottr:listSep
- Specifies
how to translate source values into lists using the string value
of the source value. The default values are respectively:
(
,)
and,
. A list value may represent a nested list of arbitrary depth.ottr:listStart
andottr:listEnd
must be a one-character string that specifies respectively the start and end of a list.ottr:listSep
is a string that specifies how the list elements are separated. The list element values are trimmed for white space. These list properties may only be used if theottr:type
is a list type [1]. Example: if the source value is"(( a , b ), (c , d))"
, and theottr:type
is(rdf:List rdf:List xsd:string)
, then the argument value becomes the RDF list(( "a" "b" )("c" "d"))
.
This example is similar to a previous example, but note that the source data is slightly changed to illustrate the functionality of argument maps.
[] a ottr:InstanceMap ; ottr:source [ a ottr:H2Source ] ; ottr:query """ SELECT 'First Name', 'Age', 'City', 'Homepage' FROM CSVREAD('address.csv'); """ ; ottr:template ex:Person2 ; ottr:argumentMaps ( [ ] ## empty Argument map [ ottr:type xsd:integer ] [ ottr:languageTag "en" ] [ ottr:type ottr:IRI; ottr:nullValue ottr:none ] ) .
Assuming that the contents of address.csv
are
First Name | Last Name | Age | City | Homepage |
---|---|---|---|---|
Ann | Annsen | 30 | Amsterdam | http://example.com/Ann |
Bob | Bobson | 31 | Berlin | http://example.com/Bob |
Carl | Carlson | 32 | Cairo | NULL |
then the instance map will produce the following instances, here shown in stOTTR [3] format:
ex:Person2 ("Ann", 30, "Amsterdam"@en, <http://example.com/Ann> ) . ex:Person2 ("Bob", 31, "Berlin"@en, <http://example.com/Bob> ) . ex:Person2 ("Carl", 32, "Cairo"@en, none ) .
3 Vocabulary listings
The classes and properties of the bOTTR vocabulary are presented in the next sections. Each section contains a table. The bOTTR ontology is produced from these tables by converting the tables into OTTR template instances whose expansion, plus some additional ontology metadata, gives the ontology. This process is shown in the appendix.
The tables use the following formatting rules:
- Column headers with a trailing question mark indicate that a value in this column is optional.
- Table cells with a trailing
*
are not translated into the ontology. This is done in the following cases:- Cells that contain lists.
- Cells that contain the value
rdfs:Resource
.
3.1 Classes
The classes of the vocabulary are listed in Table 1
Each row represents a owl:Class
with optional superclass
relationship (using rdfs:subClassOf
), textual definition
(skos:definition
) and optional note (skos:note
).
Class IRI | Superclass IRI? | Definition | Note? |
---|---|---|---|
ottr:InstanceMap |
'' | ||
ottr:Source |
'' | ||
ottr:StringSource |
ottr:Source |
'' | |
ottr:RDFSource |
ottr:Source |
'' | |
ottr:JDBCSource |
ottr:StringSource |
'' | |
ottr:SPARQLEndpointSource |
ottr:RDFSource |
'' | |
ottr:RDFFileSource |
ottr:RDFSource |
'' | |
ottr:H2Source |
ottr:StringSource |
'' | |
ottr:ArgumentMap |
'' |
3.2 Properties
The properties of the vocabulary are listed in Table
2. Each row represents a property of the given
property type with optional domain (rdfs:domain
) and optional
range (rdfs:range
), textual definition (skos:definition
) and
optional node (skos:note
).
Property IRI | Property type | Domain IRI? | Range IRI? | Definition | Note? |
---|---|---|---|---|---|
ottr:template |
owl:ObjectProperty |
ottr:InstanceMap |
ottr:Template * |
'' | |
ottr:argumentMaps |
owl:ObjectProperty |
ottr:InstanceMap |
List of ottr:ArgumentMap * |
'' | |
ottr:source |
owl:ObjectProperty |
ottr:InstanceMap |
ottr:Source |
'' | |
ottr:query |
owl:DatatypeProperty |
ottr:InstanceMap |
xsd:string |
'' | |
ottr:sourceURL |
owl:DatatypeProperty |
ottr:Source |
xsd:string |
'' | |
ottr:username |
owl:DatatypeProperty |
ottr:JDBCSource |
xsd:string |
'' | |
ottr:password |
owl:DatatypeProperty |
ottr:JDBCSource |
xsd:string |
'' | |
ottr:jdbcDriver |
owl:DatatypeProperty |
ottr:JDBCSource |
xsd:string |
'' | |
ottr:fetchSize |
owl:DatatypeProperty |
ottr:JDBCSource |
xsd:integer |
'' | |
ottr:type |
owl:ObjectProperty |
ottr:ArgumentMap |
ottr:Type |
'' | |
ottr:nullValue |
owl:AnnotationProperty |
ottr:ArgumentMap |
(rdfs:Resource ) |
'' | |
ottr:languageTag |
owl:DatatypeProperty |
ottr:ArgumentMap |
xsd:string |
'' | |
ottr:labelledBlankPrefix |
owl:DatatypeProperty |
ottr:ArgumentMap |
xsd:string |
'' | |
ottr:listSep |
owl:DatatypeProperty |
ottr:ArgumentMap |
xsd:string |
'' | |
ottr:listStart |
owl:DatatypeProperty |
ottr:ArgumentMap |
xsd:string |
'' | |
ottr:listEnd |
owl:DatatypeProperty |
ottr:ArgumentMap |
xsd:string |
'' |
4 Appendix
4.1 bOTTR Templates
We eat dog food and use OTTR templates to produce the bOTTR OWL ontology from the vocabulary listing tables above. The bOTTR ontology is produced from the templates listed below and those used by wOTTR [2].
4.1.1 Property template
o-bottr:Property a ottr:Template ; ottr:parameters ( [ ottr:variable _:IRI; ottr:type ottr:IRI ] [ ottr:variable _:type; ottr:type ottr:IRI ] [ ottr:variable _:domain; ottr:type owl:Class; ottr:modifier ottr:optional ] [ ottr:variable _:range; ottr:type owl:Class; ottr:modifier ottr:optional ] [ ottr:variable _:definition; ottr:type xsd:string; ottr:modifier ottr:optional ] [ ottr:variable _:note; ottr:type xsd:string; ottr:modifier ottr:optional ] ) ; ottr:pattern [ ottr:of ottr:Triple; ottr:values ( _:IRI rdf:type _:type ) ] , [ ottr:of ottr:Triple; ottr:values ( _:IRI rdfs:domain _:domain ) ] , [ ottr:of ottr:Triple; ottr:values ( _:IRI rdfs:range _:range ) ] , [ ottr:of <http://spec.ottr.xyz/wOTTR/0.4.4/tpl/Term>; ottr:values ( _:IRI _:definition _:note ) ] .
5 References
- mOTTR
- https://spec.ottr.xyz/mOTTR/0.1.0/
- wOTTR
- https://spec.ottr.xyz/wOTTR/0.4.4/
- stOTTR
- https://spec.ottr.xyz/stOTTR/0.1.0/
- RDF 1.1 Turtle
- https://www.w3.org/TR/turtle/