The bOTTR vocabulary extends the wOTTR [1] 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.

The central notion 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 be a ottr:Signature [1],
• a ottr:source, which must be a ottr:Source,
• a ottr:query, which must be a xsd:string and a valid query over the specified ottr: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, and
• optionally an ottr:blankNodeScope, which may be any RDF term, see 2.2.1 below.

The result of processing a set of ottr:InstanceMap-s is the set of instances resulting from each of the ottr:InstanceMap-s.

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.

[] a ottr:InstanceMap ;
  ottr:source ex:rdfSource ;
  ottr:query """
    SELECT ?s ?p ?o
    WHERE { ?s ?p ?o }
    LIMIT 10
  """;
  ottr:template ottr:Triple .

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 an 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 [1] of the argument value. If the source is an ottr:RDFSource and the type of the source value is compatible [3] with the specified ottr: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 a ottr:StringSource, then the string value of the source value is cast to the specified ottr: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 of ottr:type. A blank node given here is written in the mapping document, so it is one blank node in the blank node scope [2] of that document and not in the scope of any ottr:InstanceMap (see 2.2.1): every source value it replaces, in every ottr:ArgumentMap specifying it, denotes that same blank node. Use ottr:blankNodeFresh where each missing value is to produce a blank node of its own.

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 the ottr:labelledBlankPrefix, then the argument value becomes a labelled blank node where the sting value of the source value following the ottr:labelledBlankPrefix becomes the label. Example: if the ottr: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 of ottr:type. The label is interpreted in the blank node scope [2] of the ottr:InstanceMap, see 2.2.1: the same label produces the same blank node within that scope and a different one outside it.

ottr:languageTag

Specifies the language tag of the argument value. If this value is set, then the source value becomes a language tagged literal where the lexical value is the string value of the source value.

ottr:languageTagSep

Specifies a separator string used to split the string value of the source value into a lexical value and a language tag. The separator is matched at the last occurrence in the string value, so that the part before the separator becomes the lexical value and the part after becomes the language tag. For example, if the separator is "@@" and the source value is "hello@@en", then the argument value becomes "hello"@en. Cannot be combined with ottr:languageTag, ottr:type, or ottr:datatypeSep.

ottr:datatypeSep

Specifies a separator string used to split the string value of the source value into a lexical value and a datatype IRI. The separator is matched at the last occurrence in the string value, so that the part before the separator becomes the lexical value and the part after becomes the datatype IRI (which may be a prefixed name). For example, if the separator is "^^" and the source value is "42^^xsd:integer", then the argument value becomes "42"^^xsd:integer. Cannot be combined with ottr:languageTag, ottr:languageTagSep, or ottr:type.

ottr:blankNodeFresh

Specifies a list of string values that should produce a fresh (unlabelled) blank node instead of being translated to a literal or IRI. This is useful for source values that represent missing or null identifiers, such as empty strings or database NULL representations. Each time a matching value is encountered a new, fresh blank node is produced [2], distinct from every other blank node whatever the blank node scope. This property may be specified for all values of ottr:type.

ottr:translationTable

Specifies an ottr:TranslationTable, a set of ottr:entry resources each pairing one ottr:inValue with one ottr:outValue, inspired by the D2RQ Mapping Language's translation tables [2]. If the source is a ottr:StringSource, the source value matches an entry whose ottr:inValue is the plain (untyped, non-language-tagged) literal of that string value. If the source is an ottr:RDFSource, the source value matches an entry whose ottr:inValue is the RDF term read from the source, unchanged. A matching entry's ottr:outValue becomes the argument value as-is, without being cast to ottr:type – unless it is a blank node, in which case the argument value is instead a fresh blank node [2], as with ottr:blankNodeFresh. The table is checked after ottr:nullValue, ottr:labelledBlankPrefix and ottr:blankNodeFresh, and before ottr:type and the other value-parsing properties below. Unlike the D2RQ Mapping Language [2], a source value with no matching ottr:entry is not omitted: it is processed as if no ottr:translationTable were given, subject to the argument map's other properties.

ottr:booleanTrue, ottr:booleanFalse

Specify lists of string values that should be mapped to xsd:boolean true and false respectively. These properties only apply when ottr:type is xsd:boolean. This is useful for sources that represent boolean values with strings such as "Y", "N", "1", "0", etc. Example: ottr:booleanTrue ("Y" "1" "TRUE") and ottr:booleanFalse ("N" "0" "FALSE").

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 and ottr: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 the ottr:type is a list type [3]. Example: if the source value is "(( a , b ), (c , d))", and the ottr:type is (rdf:List rdf:List xsd:string), then the argument value becomes the RDF list (( "a" "b" )("c" "d")).

[] 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 ] 
  ) .

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 ) .

[] a ottr:InstanceMap ;
  ottr:source [ a ottr:H2Source ] ;
  ottr:query """
    SELECT id, label FROM CSVREAD('entities.csv');
  """ ;
  ottr:template ex:Entity ;
  ottr:argumentMaps (
    [ ottr:type ottr:IRI ]
    [ ottr:languageTagSep "@@" ]
  ) .

ex:Entity (<http://example.com/ex/1>, "Hello"@en ) .
ex:Entity (<http://example.com/ex/2>, "Bonjour"@fr ) .

[] a ottr:InstanceMap ;
  ottr:source [ a ottr:H2Source ] ;
  ottr:query """
    SELECT id, value, active FROM CSVREAD('data.csv');
  """ ;
  ottr:template ex:Record ;
  ottr:argumentMaps (
    [ ottr:blankNodeFresh ( "" "NULL" ) ]
    [ ottr:datatypeSep "^^" ]
    [ ottr:type xsd:boolean ;
      ottr:booleanTrue  ( "Y" "1" "TRUE" ) ;
      ottr:booleanFalse ( "N" "0" "FALSE" ) ]
  ) .

ex:Record (<http://example.com/ex/1>, 42, true ) .
ex:Record (_:b0, "hello", false ) .

[] a ottr:InstanceMap ;
  ottr:source [ a ottr:H2Source ] ;
  ottr:query """
    SELECT id, color FROM CSVREAD('objects.csv');
  """ ;
  ottr:template ex:ShinyObject ;
  ottr:argumentMaps (
    [ ottr:type ottr:IRI ]
    [ ottr:type ottr:IRI ;
      ottr:translationTable [
        ottr:entry
          [ ottr:inValue "R" ; ottr:outValue ex:red ] ,
          [ ottr:inValue "G" ; ottr:outValue ex:green ] ,
          [ ottr:inValue "B" ; ottr:outValue ex:blue ]
      ]
    ]
  ) .

ex:ShinyObject (<http://example.com/obj/1>, ex:red ) .
ex:ShinyObject (<http://example.com/obj/2>, ex:green ) .

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).

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).

Each term is annotated with rdfs:isDefinedBy, naming the version IRI of the ontology that declares it. The table below adds, for the terms whose history is known, the versions bounding the term's life. A term with no row here carries no such stamp: this document only records history from 0.1.2 onwards, which is as far back as the change notes go.

Introduced

the term did not exist before this version.

Changed

the term existed, but its declaration or meaning differed before this version.

Deprecated

the term should not be used from this version on.

A term is valid over the half-open interval from, and including, Introduced to Deprecated.

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 [1].