docs: Port "defining ontologies" documentation to markdown

22 files changed, 392 insertions, 471 deletions

diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-1.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-1.rq
deleted file mode 100644
index 326caa25a..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-1.rq
+++ /dev/null
@@ -1,5 +0,0 @@
-INSERT DATA { <cat> a ex:Mammal .
-              <dog> a ex:Mammal .
-
-              <peter> a ex:Mammal ;
-                    ex:pets <cat>, <dog> }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-2.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-2.txt
deleted file mode 100644
index 9674e4f21..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-2.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-ex:cromosomes a rdf:Property;
-              rdfs:domain ex:Eukaryote;
-              rdfs:range xsd:integer;
-              nrl:maxCardinality 1.
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-3.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-3.rq
deleted file mode 100644
index c5502e149..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-cardinality-3.rq
+++ /dev/null
@@ -1,8 +0,0 @@
-# This will fail
-INSERT DATA { <cat> a ex:Mammal;
-                    ex:cromosomes 38;
-                    ex:cromosomes 42 }
-
-# This will succeed
-INSERT DATA { <donald> a ex:Mammal;
-                       ex:cromosomes 47 }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-1.txt
deleted file mode 100644
index 6bb7c41d5..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-1.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-ex:Eukaryote a rdfs:Class;
-             rdfs:subClassOf rdfs:Resource;
-             rdfs:comment "An eukaryote".
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-2.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-2.txt
deleted file mode 100644
index 3634ca859..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-2.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-ex:Animal a rdfs:Class;
-          rdfs:subClassOf ex:Eukaryote;
-          rdfs:comment "An animal".
-
-ex:Plant a rdfs:Class;
-          rdfs:subClassOf ex:Eukaryote;
-          rdfs:comment "A plant".
-
-ex:Mammal a rdfs:Class;
-          rdfs:subClassOf ex:Animal;
-          rdfs:comment "A mammal".
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-3.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-3.rq
deleted file mode 100644
index c6951039e..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-classes-3.rq
+++ /dev/null
@@ -1,2 +0,0 @@
-INSERT DATA { <merry> a ex:Mammal }
-INSERT DATA { <treebeard> a ex:Animal, ex:Plant }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-1.txt
deleted file mode 100644
index e704b3758..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-1.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-ex:name a rdf:Property;
-        rdfs:domain ex:Mammal;
-        rdfs:range xsd:string;
-        nrl:fulltextIndexed true;
-        nrl:weight 10.
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-2.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-2.rq
deleted file mode 100644
index 1b13d99ac..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-fts-indexes-2.rq
+++ /dev/null
@@ -1,2 +0,0 @@
-SELECT { ?mammal a ex:Mammal;
-                 fts:match "timmy" }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-indexes-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-indexes-1.txt
deleted file mode 100644
index 5c2f113ca..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-indexes-1.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-# Make queries on ex:dateOfBirth faster
-ex:Mammal a rdfs:Class;
-          rdfs:subClassOf ex:Animal;
-          rdfs:comment "A mammal";
-          nrl:domainIndex ex:dateOfBirth.
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-namespaces-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-namespaces-1.txt
deleted file mode 100644
index 93132adaf..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-namespaces-1.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-# These prefixes will be used in the definition of the ontology,
-# thus must be explicitly defined
-@prefix nrl: <http://tracker.api.gnome.org/ontology/v3/nrl#> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-# This is our example namespace
-@prefix ex: <http://example.org/#>
-
-ex: a nrl:Namespace, nrl:Ontology
-    nrl:prefix "ex"
-    rdfs:comment "example ontology"
-    nrl:lastModified "2017-01-01T15:00:00Z"
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-1.txt
deleted file mode 100644
index 2a391f43e..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-1.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-ex:cromosomes a rdf:Property;
-              rdfs:domain ex:Eukaryote;
-              rdfs:range xsd:integer.
-
-ex:unicellular a rdf:Property;
-               rdfs:domain ex:Eukaryote;
-               rdfs:range xsd:bool;
-
-ex:dateOfBirth a rdf:Property;
-               rdfs:domain ex:Mammal;
-               rdfs:range xsd:dateTime;
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-2.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-2.txt
deleted file mode 100644
index c808a2575..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-2.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-ex:parent a rdf:Property;
-          rdfs:domain ex:Mammal;
-          rdfs:range ex:Mammal;
-
-ex:pet a rdf:Property;
-       rdfs:domain ex:Mammal;
-       rdfs:range ex:Eukaryote;
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-3.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-3.txt
deleted file mode 100644
index 05f8aeb18..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-3.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-ex:geneticInformation a rdf:Property;
-                      rdfs:domain ex:Eukaryote;
-                      rdfs:range xsd:string;
-
-ex:dna a rdf:Property;
-       rdfs:domain ex:Mammal;
-       rdfs:range xsd:string;
-       rdfs:subPropertyOf ex:geneticInformation.
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-4.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-4.rq
deleted file mode 100644
index 0f44af216..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-properties-4.rq
+++ /dev/null
@@ -1,5 +0,0 @@
-# These two queries should provide the exact same result(s)
-SELECT { ?animal a ex:Animal;
-                 ex:geneticInformation "AGCT" }
-SELECT { ?animal a ex:Animal;
-                 ex:dna "AGCT" }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-1.txt
deleted file mode 100644
index 14a6ed759..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-1.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-ex:geneticInformation a rdf:Property, nrl:InverseFunctionalProperty;
-                      rdfs:domain ex:Eukaryote;
-                      rdfs:range xsd:string;
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-2.rq b/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-2.rq
deleted file mode 100644
index 6459d50b5..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/defining-uniqueness-2.rq
+++ /dev/null
@@ -1,7 +0,0 @@
-# First insertion, this will succeed
-INSERT DATA { <drosophila> a ex:Eukariote;
-                           ex:geneticInformation "AGCT" }
-
-# This will fail
-INSERT DATA { <melanogaster> a ex:Eukariote;
-                             ex:geneticInformation "AGCT" }
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/example.description b/docs/reference/libtracker-sparql/examples/ontologies/example.description
deleted file mode 100644
index 10c584ef7..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/example.description
+++ /dev/null
@@ -1,16 +0,0 @@
-@prefix dsc: <http://tracker.api.gnome.org/ontology/v3/dsc#> .
-
-<virtual-ontology-uri:30-nie.ontology> a dsc:Ontology ;
-	dsc:title "Example ontology" ;
-	dsc:description "A little bit of this and that." ;
-	dsc:upstream "http://www.example.org/ontologies";
-	dsc:author "John doe, &lt;john@example.org&gt;";
-	dsc:editor "Jane doe, &lt;jane@example.org&gt;";
-	dsc:gitlog "http://git.example.org/cgit/tracker/log/example.ontology";
-	dsc:contributor "someone else, &lt;some1@example.org&gt;";
-
-	dsc:localPrefix "ex" ;
-	dsc:baseUrl "http://www.example.org/ontologies/ex#";
-	dsc:relativePath "./10-ex.ontology" ;
-
-	dsc:copyright "All rights given away".
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-1.txt b/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-1.txt
deleted file mode 100644
index a65eb5a7c..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-1.txt
+++ /dev/null
@@ -1 +0,0 @@
-ex:self a ex:Mammal.
diff --git a/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-2.rq b/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-2.rq
deleted file mode 100644
index 552849c2c..000000000
--- a/docs/reference/libtracker-sparql/examples/ontologies/predefined-elements-2.rq
+++ /dev/null
@@ -1,2 +0,0 @@
-INSERT DATA { ex:self ex:pets <cat> .
-              <cat> ex:pets ex:self }
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index 6e72986bb..7a7e205d8 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -1,5 +1,6 @@
 content = [
   'overview.md',
+  'ontologies.md',
   'limits.md',
   'performance.md',
   'sparql-and-tracker.md',
diff --git a/docs/reference/libtracker-sparql/ontologies.md b/docs/reference/libtracker-sparql/ontologies.md
new file mode 100644
index 000000000..94fb85c23
--- /dev/null
+++ b/docs/reference/libtracker-sparql/ontologies.md
@@ -0,0 +1,391 @@
+Title: 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, inheritance
+  and indexes.
+- Dublin Core (DC), defining common superproperties for documents
+
+Ontologies are Turtle files with the .ontology extension, Tracker parses all
+ontology files from the given directory. The individual ontology files 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:
+
+```turtle
+# These prefixes will be used in the definition of the ontology,
+# thus must be explicitly defined
+@prefix nrl: <http://tracker.api.gnome.org/ontology/v3/nrl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# This is our example namespace
+@prefix ex: <http://example.org/#>
+
+ex: a nrl:Namespace, nrl:Ontology
+    nrl:prefix "ex"
+    rdfs:comment "example ontology"
+    nrl:lastModified "2017-01-01T15:00:00Z"
+```
+
+### 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:
+
+```RDF
+ex:Eukaryote a rdfs:Class;
+             rdfs:subClassOf rdfs:Resource;
+             rdfs:comment "An eukaryote".
+```
+
+By convention all classes use CamelCase names, although class names
+are not restricted. The allowed charset is UTF-8.
+
+Declaring subclasses is possible:
+
+```turtle
+ex:Animal a rdfs:Class;
+          rdfs:subClassOf ex:Eukaryote;
+          rdfs:comment "An animal".
+
+ex:Plant a rdfs:Class;
+          rdfs:subClassOf ex:Eukaryote;
+          rdfs:comment "A plant".
+
+ex:Mammal a rdfs:Class;
+          rdfs:subClassOf ex:Animal;
+          rdfs:comment "A mammal".
+```
+
+With such classes defined, resources may be inserted to the endpoint,
+eg. with the SPARQL:
+
+```SPARQL
+INSERT DATA { <merry> a ex:Mammal }
+INSERT DATA { <treebeard> a ex:Animal, ex:Plant }
+```
+
+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.
+
+```turtle
+ex:cromosomes a rdf:Property;
+              rdfs:domain ex:Eukaryote;
+              rdfs:range xsd:integer.
+
+ex:unicellular a rdf:Property;
+               rdfs:domain ex:Eukaryote;
+               rdfs:range xsd:bool;
+
+ex:dateOfBirth a rdf:Property;
+               rdfs:domain ex:Mammal;
+               rdfs:range xsd:dateTime;
+```
+
+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 dromedaryCase names, although property names are not
+restricted. The allowed charset is UTF-8.
+
+The following basic types are supported:
+
+- `xsd:boolean`
+- `xsd:string` and `rdf:langString`
+- `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 1st 1 AD, with microsecond resolution.
+
+Of course, properties can also point to resources of the same or
+other classes, so stored resources can conform a graph:
+
+```turtle
+ex:parent a rdf:Property;
+          rdfs:domain ex:Mammal;
+          rdfs:range ex:Mammal;
+
+ex:pet a rdf:Property;
+       rdfs:domain ex:Mammal;
+       rdfs:range ex:Eukaryote;
+```
+
+There is also inheritance of properties, an example would be a property
+in a subclass concretizing a more generic property from a superclass.
+
+```turtle
+ex:geneticInformation a rdf:Property;
+                      rdfs:domain ex:Eukaryote;
+                      rdfs:range xsd:string;
+
+ex:dna a rdf:Property;
+       rdfs:domain ex:Mammal;
+       rdfs:range xsd:string;
+       rdfs:subPropertyOf ex:geneticInformation.
+```
+
+SPARQL queries are expected to provide the same result when queried
+for a property or one of its superproperties.
+
+```SPARQL
+# These two queries should provide the exact same result(s)
+SELECT { ?animal a ex:Animal;
+                 ex:geneticInformation "AGCT" }
+SELECT { ?animal a ex:Animal;
+                 ex:dna "AGCT" }
+```
+
+### Defining cardinality of properties
+
+By default, properties are multivalued, there are no restrictions in
+the number of values a property can store.
+
+```SPARQL
+INSERT DATA {
+  <cat> a ex:Mammal .
+  <dog> a ex:Mammal .
+
+  <peter> a ex:Mammal ;
+     ex:pets <cat>, <dog>
+}
+```
+
+Wherever this is not desirable, cardinality can be limited on properties
+through nrl:maxCardinality.
+
+```turtle
+ex:cromosomes a rdf:Property;
+              rdfs:domain ex:Eukaryote;
+              rdfs:range xsd:integer;
+              nrl:maxCardinality 1.
+```
+
+This will raise an error if the SPARQL updates in the endpoint end up
+in the property inserted multiple times.
+
+```SPARQL
+# This will fail
+INSERT DATA { <cat> a ex:Mammal;
+                    ex:cromosomes 38;
+                    ex:cromosomes 42 }
+
+# This will succeed
+INSERT DATA { <donald> a ex:Mammal;
+                       ex:cromosomes 47 }
+```
+
+Tracker does not implement support for other maximum cardinalities
+than 1.
+
+<!---
+    XXX: explain how cardinality affects subproperties, superproperties
+--->
+
+### 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.
+
+```turtle
+ex:geneticInformation a rdf:Property, nrl:InverseFunctionalProperty;
+                      rdfs:domain ex:Eukaryote;
+                      rdfs:range xsd:string;
+```
+
+With that in place, no two resources can have the same value on the
+property.
+
+```SPARQL
+# First insertion, this will succeed
+INSERT DATA { <drosophila> a ex:Eukariote;
+                           ex:geneticInformation "AGCT" }
+
+# This will fail
+INSERT DATA { <melanogaster> a ex:Eukariote;
+                             ex:geneticInformation "AGCT" }
+```
+
+<!---
+    XXX: explain how inverse functional proeprties affect sub/superproperties
+--->
+
+### 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 nrl:domainIndex in the class definition:
+
+```turtle
+# Make queries on ex:dateOfBirth faster
+ex:Mammal a rdfs:Class;
+          rdfs:subClassOf ex:Animal;
+          rdfs:comment "A mammal";
+          nrl:domainIndex ex:dateOfBirth.
+```
+
+Classes may define multiple domain indexes.
+
+**Note**: 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 nrl:fulltextIndexed:
+
+```turtle
+ex:name a rdf:Property;
+        rdfs:domain ex:Mammal;
+        rdfs:range xsd:string;
+        nrl:fulltextIndexed true;
+        nrl:weight 10.
+```
+
+Weighting can also be applied, so certain properties rank higher than others
+in full-text search queries. With nrl:fulltextIndexed in place, sparql
+queries may use full-text search capabilities:
+
+```SPARQL
+SELECT { ?mammal a ex:Mammal;
+                 fts:match "timmy" }
+```
+
+### 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.
+
+```turtle
+ex:self a ex:Mammal.
+```
+
+Usage does not differ in use from the elements of that same class that
+could be inserted in the endpoint.
+
+```SPARQL
+INSERT DATA { ex:self ex:pets <cat> .
+              <cat> ex:pets ex:self }
+```
+
+### Accompanying metadata
+
+Ontology files are optionally accompanied by description files, those have
+the same basename, but the ".description" extension.
+
+```turtle
+@prefix dsc: <http://tracker.api.gnome.org/ontology/v3/dsc#> .
+
+<virtual-ontology-uri:30-nie.ontology> a dsc:Ontology ;
+	dsc:title "Example ontology" ;
+	dsc:description "A little bit of this and that." ;
+	dsc:upstream "http://www.example.org/ontologies";
+	dsc:author "John doe, &lt;john@example.org&gt;";
+	dsc:editor "Jane doe, &lt;jane@example.org&gt;";
+	dsc:gitlog "http://git.example.org/cgit/tracker/log/example.ontology";
+	dsc:contributor "someone else, &lt;some1@example.org&gt;";
+
+	dsc:localPrefix "ex" ;
+	dsc:baseUrl "http://www.example.org/ontologies/ex#";
+	dsc:relativePath "./10-ex.ontology" ;
+
+	dsc:copyright "All rights given away".
+```
+
+## Updating an ontology
+
+As software evolves, sometimes changes in the ontology are unavoidable.
+Tracker can transparently handle certain ontology changes on existing
+databases.
+
+1. Adding a class.
+2. Removing a class.
+   All resources will be removed from this class, and all related
+   properties will disappear.
+3. Adding a property.
+4. Removing a property.
+   The property will disappear from all elements pertaining to the
+   class in domain of the property.
+5. Changing rdfs:range of a property.
+   The following conversions are allowed:
+
+    - `xsd:integer` to `xsd:bool`, `xsd:double` and `xsd:string`</listitem></varlistentry>
+    - `xsd:double` to `xsd:bool`, `xsd:integer` and `xsd:string`</listitem></varlistentry>
+    - `xsd:string` to `xsd:bool`, `xsd:integer` and `xsd:double`</listitem></varlistentry>
+
+6. Adding and removing `nrl:domainIndex` from a class.
+7. Adding and removing `nrl:fulltextIndexed` from a property.
+8. Changing the `nrl:weight` on a property.
+9. Removing `nrl:maxCardinality` from a property.
+
+<!---
+    XXX: these need documenting too
+    add intermediate superproperties
+    add intermediate superclasses
+    remove intermediate superproperties
+    remove intermediate superclasses
+--->
+
+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` is 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.
diff --git a/docs/reference/libtracker-sparql/ontologies.xml b/docs/reference/libtracker-sparql/ontologies.xml
deleted file mode 100644
index 26e3f4e7a..000000000
--- a/docs/reference/libtracker-sparql/ontologies.xml
+++ /dev/null
@@ -1,352 +0,0 @@
-<?xml version='1.0' encoding="UTF-8"?>
-
-<part id="tracker-ontologies" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <title>Defining ontologies</title>
-  <partintro>
-    <para>
-      An ontology defines the entities that a Tracker endpoint can store, as
-      well as their properties and the relationships between different entities.
-    </para>
-    <para>
-      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:
-    </para>
-
-    <formalpara>
-      <title><systemitem>XML Schema (XSD).</systemitem></title>
-      <para>Defining basic types.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Resource Description Framework (RDF).</systemitem></title>
-      <para>Defining classes, properties and inheritance</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Nepomuk Resource Language (NRL).</systemitem></title>
-      <para>Defining resource uniqueness and cardinality</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Dublin Core (DC).</systemitem></title>
-      <para>Defining common superproperties for documents</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Nepomuk Annotation Ontology (NAO).</systemitem></title>
-      <para>Implementing tagging and annotations</para>
-    </formalpara>
-
-    <para>
-      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.
-    </para>
-
-    <para>
-      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.
-    </para>
-  </partintro>
-
-  <chapter id="creating-ontology">
-    <title>Creating an ontology</title>
-    <section id="defining-namespaces">
-      <title>Defining a namespace</title>
-      <para>
-	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:
-      </para>
-      <programlisting><xi:include href="examples/ontologies/defining-namespaces-1.txt" parse="text"/></programlisting>
-    </section>
-    <section id="defining-classes">
-      <title>Defining classes</title>
-      <para>
-	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:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-classes-1.txt" parse="text"/></programlisting>
-      <para>
-	By convention all classes use CamelCase names, although class names
-	are not restricted. The allowed charset is UTF-8.
-      </para>
-      <para>
-	Declaring subclasses is possible:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-classes-2.txt" parse="text"/></programlisting>
-      <para>
-	With such classes defined, resources may be inserted to the endpoint,
-	eg. with the SPARQL:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-classes-3.rq" parse="text"/></programlisting>
-      <para>
-	Note that multiple inheritance is possible, resources will just inherit
-	all properties from all classes and superclasses.
-      </para>
-    </section>
-    <section id="defining-properties">
-      <title>Defining properties</title>
-      <para>
-	Properties relate to a class, so all resources pertaining to that class
-	can define values for these.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-properties-1.txt" parse="text"/></programlisting>
-      <para>
-	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.
-      </para>
-      <para>
-	The following basic types are supported:
-      </para>
-      <formalpara>
-	<title><systemitem>xsd:boolean</systemitem></title>
-      </formalpara>
-      <formalpara>
-	<title><systemitem>xsd:string</systemitem></title>
-      </formalpara>
-      <formalpara>
-	<title><systemitem>xsd:integer</systemitem></title>
-	<para>Ranging from -2^63 to 2^63-1.</para>
-      </formalpara>
-      <formalpara>
-	<title><systemitem>xsd:double</systemitem></title>
-	<para>Able to store a 8 byte IEEE floating point number.</para>
-      </formalpara>
-      <formalpara>
-	<title><systemitem>xsd:date and xsd:dateTime</systemitem></title>
-	<para>
-	  Able to store dates and times since January 1, 1970 UTC, with
-	  millisecond resolution.
-	</para>
-      </formalpara>
-      <para>
-	Of course, properties can also point to resources of the same or
-	other classes, so stored resources can conform a graph:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-properties-2.txt" parse="text"/></programlisting>
-      <para>
-	There is also inheritance of properties, an example would be a property
-	in a subclass concretizing a more generic property from a superclass.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-properties-3.txt" parse="text"/></programlisting>
-      <para>
-	SPARQL queries are expected to provide the same result when queried
-	for a property or one of its superproperties.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-properties-4.rq" parse="text"/></programlisting>
-    </section>
-    <section id="defining-cardinality">
-      <title>Defining cardinality of properties</title>
-      <para>
-	By default, properties are multivalued, there are no restrictions in
-	the number of values a property can store.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-cardinality-1.rq" parse="text"/></programlisting>
-      <para>
-	Wherever this is not desirable, cardinality can be limited on properties
-	through nrl:maxCardinality.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-cardinality-2.txt" parse="text"/></programlisting>
-      <para>
-	This will raise an error if the SPARQL updates in the endpoint end up
-	in the property inserted multiple times.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-cardinality-3.rq" parse="text"/></programlisting>
-      <note>
-	Tracker does not implement support for other maximum cardinalities
-	than 1.
-      </note>
-      <!--
-	  XXX: explain how cardinality affects subproperties, superproperties
-	-->
-    </section>
-    <section id="defining-uniqueness">
-      <title>Defining uniqueness</title>
-      <para>
-	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.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-uniqueness-1.txt" parse="text"/></programlisting>
-      <para>
-	With that in place, no two resources can have the same value on the
-	property.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-uniqueness-2.rq" parse="text"/></programlisting>
-      <!--
-	  XXX: explain how inverse functional proeprties affect sub/superproperties
-	-->
-    </section>
-    <section id="defining-indexes">
-      <title>Defining indexes</title>
-      <para>
-	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 nrl:domainIndex in the class definition:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-indexes-1.txt" parse="text"/></programlisting>
-      <para>
-	Classes may define multiple domain indexes.
-      </para>
-      <note>
-	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.
-      </note>
-    </section>
-    <section id="defining-fts-indexes">
-      <title>Defining full-text search properties</title>
-      <para>
-	Tracker provides nonstandard full-text search capabilities, in order to use
-	these, the string properties can use nrl:fulltextIndexed:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-fts-indexes-1.txt" parse="text"/></programlisting>
-      <para>
-	Weighting can also be applied, so certain properties rank higher than others
-	in full-text search queries. With nrl:fulltextIndexed in place, sparql
-	queries may use full-text search capabilities:
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/defining-fts-indexes-2.rq" parse="text"/></programlisting>
-    </section>
-    <section id="predefined-elements">
-      <title>Predefined elements</title>
-      <para>
-	It may be desirable for the ontology to offer predefined elements of a
-	certain class, which can then be used by the endpoint.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/predefined-elements-1.txt" parse="text"/></programlisting>
-      <para>
-	Usage does not differ in use from the elements of that same class that
-	could be inserted in the endpoint.
-      </para>
-      <programlisting><xi:include href="./examples/ontologies/predefined-elements-2.rq" parse="text"/></programlisting>
-    </section>
-  </chapter>
-
-  <chapter id="accompanying-metadata">
-    <title>Accompanying metadata</title>
-    <para>
-      Ontology files are optionally accompanied by description files, those have
-      the same basename, but the ".description" extension.
-    </para>
-    <programlisting><xi:include href="./examples/ontologies/example.description" parse="text"/></programlisting>
-  </chapter>
-
-  <chapter id="updating-ontology">
-    <title>Updating an ontology</title>
-
-    <para>
-      As software evolves, sometimes changes in the ontology are unavoidable.
-      Tracker can transparently handle certain ontology changes on existing
-      databases.
-    </para>
-
-    <formalpara>
-      <title><systemitem>Adding a class.</systemitem></title>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Removing a class.</systemitem></title>
-      <para>
-	All resources will be removed from this class, and all related
-	properties will disappear.
-      </para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Adding a property.</systemitem></title>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Removing a property.</systemitem></title>
-      <para>
-	The property will disappear from all elements pertaining to the
-	class in domain of the property.
-      </para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Changing rdfs:range of a property.</systemitem></title>
-      <para>
-	The following conversions are allowed:
-      </para>
-      <variablelist>
-	<varlistentry><listitem>xsd:integer to xsd:bool, xsd:double and xsd:string</listitem></varlistentry>
-	<varlistentry><listitem>xsd:double to xsd:bool, xsd:integer and xsd:string</listitem></varlistentry>
-	<varlistentry><listitem>xsd:string to xsd:bool, xsd:integer and xsd:double</listitem></varlistentry>
-      </variablelist>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Adding and removing nrl:domainIndex from a class.</systemitem></title>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Adding and removing nrl:fulltextIndexed from a property.</systemitem></title>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Changing the nrl:weight on a property.</systemitem></title>
-    </formalpara>
-    <formalpara>
-      <title><systemitem>Removing nrl:maxCardinality from a property.</systemitem></title>
-    </formalpara>
-    <!--
-	XXX: these need documenting too
-	add intermediate superproperties
-	add intermediate superclasses
-	remove intermediate superproperties
-	remove intermediate superclasses
-      -->
-
-    <para>
-      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:
-    </para>
-    <variablelist>
-      <varlistentry><listitem>
-	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.
-      </listitem></varlistentry>
-      <varlistentry><listitem>
-	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.
-      </listitem></varlistentry>
-      <varlistentry><listitem>
-	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.
-      </listitem></varlistentry>
-      <varlistentry><listitem>
-	Properties can not move across classes, thus any change in
-	rdfs:domain forbidden.
-      </listitem></varlistentry>
-      <varlistentry><listitem>
-	You can not add nrl:maxCardinality restrictions on properties that
-	are not being newly added.
-      </listitem></varlistentry>
-      <varlistentry><listitem>
-	You can not add nor remove nrl:InverseFunctionalProperty from a
-	property that is not being newly added.
-      </listitem></varlistentry>
-    </variablelist>
-    <para>
-      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.
-    </para>
-    <para>
-      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.
-    </para>
-  </chapter>
-</part>