# Defining ontologies

An ontology defines the entities that a Tracker endpoint can store, as well as their properties and the relationships between different entities.

Tracker internally uses the following ontologies as its base, all ontologies defined by the user of the endpoint are recommended to be build around this base:

XML Schema (XSD).

Defining basic types.

Resource Description Framework (RDF).

Defining classes, properties and inheritance

Nepomuk Resource Language (NRL).

Defining resource uniqueness and cardinality

Dublin Core (DC).

Defining common superproperties for documents

Nepomuk Annotation Ontology (NAO).

Implementing tagging and annotations

Ontologies are RDF files with the .ontology extension, Tracker parses all ontology files from the given directory. The individual ontology files may ontologies may not be self-consistent (i.e. use missing definitions), but all the ontology files as a whole must be.

Tracker loads the ontology files in alphanumeric order, it is advisable that those have a numbered prefix in order to load those at a consistent order despite future additions.

## Creating an ontology

### Defining a namespace

A namespace is the topmost layer of an individual ontology, it will contain all classes and properties defined by it. In order to define a namespace you can do:

### Defining classes

Classes are the base of an ontology, all stored resources must define themselves as "being" at least one of these classes. They all derive from the base rdfs:Resource type. To eg. define classes representing animals and plants, you can do:

By convention all classes use CamelCase names, although class names are not restricted. The allowed charset is UTF-8.

Declaring subclasses is possible:

With such classes defined, resources may be inserted to the endpoint, eg. with the SPARQL:

Note that multiple inheritance is possible, resources will just inherit all properties from all classes and superclasses.

### Defining properties

Properties relate to a class, so all resources pertaining to that class can define values for these.

The class the property belongs to is defined by rdfs:domain, while the data type contained is defined by rdfs:range. By convention all properties use lowerCamelCase names, although property names are not restricted. The allowed charset is UTF-8.

The following basic types are supported:

xsd:boolean

xsd:string

xsd:integer

Ranging from -2^63 to 2^63-1.

xsd:double

Able to store a 8 byte IEEE floating point number.

xsd:date and xsd:dateTime

Able to store dates and times since January 1, 1970 UTC, with millisecond resolution.

Of course, properties can also point to resources of the same or other classes, so stored resources can conform a graph:

There is also inheritance of properties, an example would be a property in a subclass concretizing a more generic property from a superclass.

SPARQL queries are expected to provide the same result when queried for a property or one of its superproperties.

### Defining cardinality of properties

By default, properties are multivalued, there are no restrictions in the number of values a property can store.

Wherever this is not desirable, cardinality can be limited on properties through nrl:maxCardinality.

This will raise an error if the SPARQL updates in the endpoint end up in the property inserted multiple times.

Tracker does not implement support for other maximum cardinalities than 1.

### Defining uniqueness

It is desirable for certain properties to keep their values unique across all resources, this can be expressed by defining the properties as being a nrl:InverseFunctionalProperty.

With that in place, no two resources can have the same value on the property.

### Defining indexes

It may be the case that SPARQL queries performed on the endpoint are known to match, sort, or filter on certain properties more often than others. In this case, the ontology may use tracker:domainIndex in the class definition:

Classes may define multiple domain indexes.

Be frugal with indexes, do not add these proactively. An index in the wrong place might not affect query performance positively, but all indexes come at a cost in disk size.

### Defining full-text search properties

Tracker provides nonstandard full-text search capabilities, in order to use these, the string properties can use tracker:fulltextIndexed:

Weighting can also be applied, so certain properties rank higher than others in full-text search queries. With tracker:fulltextIndexed in place, sparql queries may use full-text search capabilities:

### Predefined elements

It may be desirable for the ontology to offer predefined elements of a certain class, which can then be used by the endpoint.

Usage does not differ in use from the elements of that same class that could be inserted in the endpoint.

## Accompanying metadata

Ontology files are optionally accompanied by description files, those have the same basename, but the ".description" extension.

## Updating an ontology

As software evolves, sometimes changes in the ontology are unavoidable. Tracker can transparently handle certain ontology changes on existing databases.

Adding a class.

Removing a class.

All resources will be removed from this class, and all related properties will disappear.

Adding a property.

Removing a property.

The property will disappear from all elements pertaining to the class in domain of the property.

Changing rdfs:range of a property.

The following conversions are allowed:

  xsd:integer to xsd:bool, xsd:double and xsd:string
  xsd:double to xsd:bool, xsd:integer and xsd:string
  xsd:string to xsd:bool, xsd:integer and xsd:double

Adding and removing tracker:domainIndex from a class.

Adding and removing tracker:fulltextIndexed from a property.

Changing the tracker:weight on a property.

Removing nrl:maxCardinality from a property.

However, there are certain ontology changes that Tracker will find incompatible. Either because they are incoherent or resulting into situations where it can not deterministically satisfy the change in the stored data. Tracker will error out and refuse to do any data changes in these situations:

  Properties with rdfs:range being xsd:bool, xsd:date, xsd:dateTime, or any other custom class are not convertible. Only conversions covered in the list above are accepted.
  You can not add rdfs:subClassOf in classes that are not being newly added. You can not remove rdfs:subClassOf from classes. The only allowed change to rdfs:subClassOf is to correct subclasses when deleting a class, so they point a common superclass.
  You can not add rdfs:subPropertyOf to properties that are not being newly added. You can not change an existing rdfs:subPropertyOf unless it is made to point to a common superproperty. You can however remove rdfs:subPropertyOf from non-new properties.
  Properties can not move across classes, thus any change in rdfs:domain forbidden.
  You can not add nrl:maxCardinality restrictions on properties that are not being newly added.
  You can not add nor remove nrl:InverseFunctionalProperty from a property that is not being newly added.

The recommendation to bypass these situations is the same for all, use different property and class names and use SPARQL to manually migrate the old data to the new format if necessary.

High level code is in a better position to solve the possible incoherences (e.g. picking a single value if a property changes from multiple values to single value). After the manual data migration has been completed, the old classes and properties can be dropped.