[tracker/wip/carlosg/hotdoc: 29/47] docs: Adapt markdown docs to hotdoc formatting specifics
- From: Carlos Garnacho <carlosg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tracker/wip/carlosg/hotdoc: 29/47] docs: Adapt markdown docs to hotdoc formatting specifics
- Date: Thu, 26 Aug 2021 12:06:34 +0000 (UTC)
commit cd682ae01eec613eff084588d15719a392400f05
Author: Carlos Garnacho <carlosg gnome org>
Date: Tue Aug 3 11:43:02 2021 +0200
docs: Adapt markdown docs to hotdoc formatting specifics
docs/reference/libtracker-sparql/base-ontology.md | 10 +
.../libtracker-sparql/defining-ontologies.md | 394 ++++++++++++++++++++
docs/reference/libtracker-sparql/examples.md.in | 5 +-
docs/reference/libtracker-sparql/gi-index.md | 3 +
docs/reference/libtracker-sparql/implementation.md | 8 +
docs/reference/libtracker-sparql/index.md | 4 +
docs/reference/libtracker-sparql/limits.md | 6 +-
docs/reference/libtracker-sparql/ontologies.md | 404 +--------------------
docs/reference/libtracker-sparql/overview.md | 5 +-
docs/reference/libtracker-sparql/performance.md | 6 +-
.../libtracker-sparql/sparql-and-tracker.md | 6 +-
.../libtracker-sparql/sparql-functions.md | 5 +-
docs/reference/libtracker-sparql/tutorial.md | 27 +-
13 files changed, 476 insertions(+), 407 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/base-ontology.md
b/docs/reference/libtracker-sparql/base-ontology.md
new file mode 100644
index 000000000..f2f4d8368
--- /dev/null
+++ b/docs/reference/libtracker-sparql/base-ontology.md
@@ -0,0 +1,10 @@
+---
+title: Base Ontology
+short-description: Base for defining ontologies
+...
+
+The base ontology is the seed for defining application-specific
+ontologies. It defines the basic types and property/class
+definitions themselves, so that classes and properties may be
+created.
+
diff --git a/docs/reference/libtracker-sparql/defining-ontologies.md
b/docs/reference/libtracker-sparql/defining-ontologies.md
new file mode 100644
index 000000000..0208b1293
--- /dev/null
+++ b/docs/reference/libtracker-sparql/defining-ontologies.md
@@ -0,0 +1,394 @@
+---
+title: Defining Ontologies
+short-description: 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:
+
+```turtle
+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, <john example org>";
+ dsc:editor "Jane doe, <jane example org>";
+ dsc:gitlog "http://git.example.org/cgit/tracker/log/example.ontology";;
+ dsc:contributor "someone else, <some1 example org>";
+
+ 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/examples.md.in b/docs/reference/libtracker-sparql/examples.md.in
index e3340a4d9..14c6a94af 100644
--- a/docs/reference/libtracker-sparql/examples.md.in
+++ b/docs/reference/libtracker-sparql/examples.md.in
@@ -1,4 +1,7 @@
-Title: Examples
+---
+title: Examples
+short-description: Examples
+...
This chapters shows some real examples of usage of the Tracker
SPARQL Library.
diff --git a/docs/reference/libtracker-sparql/gi-index.md b/docs/reference/libtracker-sparql/gi-index.md
new file mode 100644
index 000000000..37bdfa61e
--- /dev/null
+++ b/docs/reference/libtracker-sparql/gi-index.md
@@ -0,0 +1,3 @@
+---
+title: API reference
+...
diff --git a/docs/reference/libtracker-sparql/implementation.md
b/docs/reference/libtracker-sparql/implementation.md
new file mode 100644
index 000000000..39718718e
--- /dev/null
+++ b/docs/reference/libtracker-sparql/implementation.md
@@ -0,0 +1,8 @@
+---
+title: Implementation details
+short-description: Tracker implementation specifics
+...
+
+This section highlights the chosen interpretations of the
+SPARQL specification, and specifies how to get the best of
+Tracker's implementation of the SPARQL standard.
diff --git a/docs/reference/libtracker-sparql/index.md b/docs/reference/libtracker-sparql/index.md
new file mode 100644
index 000000000..d837bdc55
--- /dev/null
+++ b/docs/reference/libtracker-sparql/index.md
@@ -0,0 +1,4 @@
+Tracker is a low-footprint, yet complete implementation of the SPARQL
+standard. It allows you to create triplestores (either in disk or in
+memory), connect to remote SPARQL endpoints (via DBus or HTTP), or
+be an endpoint yourself.
diff --git a/docs/reference/libtracker-sparql/limits.md b/docs/reference/libtracker-sparql/limits.md
index d81d1febc..94fb6ffcf 100644
--- a/docs/reference/libtracker-sparql/limits.md
+++ b/docs/reference/libtracker-sparql/limits.md
@@ -1,5 +1,7 @@
-Title: Implementation limits
-Slug: implementation-limits
+---
+title: Limits
+short-description: Implementation limits
+...
Tracker is implemented on top of SQLite, and all of its benefits and
[limits](https://www.sqlite.org/limits.html) apply. This
diff --git a/docs/reference/libtracker-sparql/ontologies.md b/docs/reference/libtracker-sparql/ontologies.md
index 94fb85c23..443ace6f1 100644
--- a/docs/reference/libtracker-sparql/ontologies.md
+++ b/docs/reference/libtracker-sparql/ontologies.md
@@ -1,391 +1,13 @@
-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, <john example org>";
- dsc:editor "Jane doe, <jane example org>";
- dsc:gitlog "http://git.example.org/cgit/tracker/log/example.ontology";;
- dsc:contributor "someone else, <some1 example org>";
-
- 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.
+---
+title: Ontologies
+short-description: Structure of the stored data
+...
+
+Ontologies define the structure of the data that the triplestore
+can hold. It defines the possible resource classes,
+the properties these classes may have, and the relation between
+the different classes as expressed by these properties.
+
+Tracker defines stock ontologies that are ready for use, but
+also allows developers to define ontologies that are tailored
+for their use.
diff --git a/docs/reference/libtracker-sparql/overview.md b/docs/reference/libtracker-sparql/overview.md
index 949d81c3f..c350313ce 100644
--- a/docs/reference/libtracker-sparql/overview.md
+++ b/docs/reference/libtracker-sparql/overview.md
@@ -1,4 +1,7 @@
-Title: Overview
+---
+title: Overview
+short-description: Library Overview
+...
Tracker SPARQL allows creating and connecting to one or more
triplestore databases. It is used by the
diff --git a/docs/reference/libtracker-sparql/performance.md b/docs/reference/libtracker-sparql/performance.md
index 7537657cb..fcd8989ca 100644
--- a/docs/reference/libtracker-sparql/performance.md
+++ b/docs/reference/libtracker-sparql/performance.md
@@ -1,5 +1,7 @@
-Title: Performance dos and donts
-Slug: performance-dos-donts
+---
+title: Performance dos and donts
+short-description: Performance dos and donts
+...
SPARQL is a very powerful query language. As it should be
suspected, this means there are areas where performance is
diff --git a/docs/reference/libtracker-sparql/sparql-and-tracker.md
b/docs/reference/libtracker-sparql/sparql-and-tracker.md
index b14b4ebfa..9c6e1e965 100644
--- a/docs/reference/libtracker-sparql/sparql-and-tracker.md
+++ b/docs/reference/libtracker-sparql/sparql-and-tracker.md
@@ -1,5 +1,7 @@
-Title: SPARQL as understood by Tracker
-Slug: sparql-and-tracker
+---
+title: SPARQL as understood by Tracker
+short-description: SPARQL as understood by Tracker
+...
This section describes the choices made by Tracker in its interpretation
of the SPARQL documents, as well as its extensions and divergences.
diff --git a/docs/reference/libtracker-sparql/sparql-functions.md
b/docs/reference/libtracker-sparql/sparql-functions.md
index 33aebd663..fe7769fc8 100644
--- a/docs/reference/libtracker-sparql/sparql-functions.md
+++ b/docs/reference/libtracker-sparql/sparql-functions.md
@@ -1,4 +1,7 @@
-Title: Builtin SPARQL functions
+---
+title: Builtin SPARQL functions
+short-description: Builtin SPARQL functions
+...
Besides the functions built in the SPARQL 1.1 syntax, type casts
and functional properties, Tracker supports a number of SPARQL
diff --git a/docs/reference/libtracker-sparql/tutorial.md b/docs/reference/libtracker-sparql/tutorial.md
index a4ec7768e..6be99511d 100644
--- a/docs/reference/libtracker-sparql/tutorial.md
+++ b/docs/reference/libtracker-sparql/tutorial.md
@@ -1,6 +1,7 @@
-----
-Title: SPARQL Tutorial
-----
+---
+title: SPARQL Tutorial
+short-description: SPARQL Tutorial
+...
# SPARQL Tutorial
@@ -26,7 +27,7 @@ Subject and object are 2 graph vertices and the predicate is the edge,
the accumulation of those triples form the full graph. For example,
the following triples:
-```
+```turtle
<a> a nfo:FileDataObject .
<a> a nmm:MusicPiece .
<a> nie:title "Images" .
@@ -34,12 +35,16 @@ the following triples:
<a> nmm:albumArtist <c> .
<a> nmm:albumArtist <d> .
<a> nmm:performer <e> .
+
<b> a nmm:MusicAlbum .
<b> nie:title "Go Off!" .
+
<c> a nmm:Artist .
<c> nmm:artistName "Jason Becker" .
+
<d> a nmm:Artist .
<d> nmm:artistName "Marty Friedman" .
+
<e> a nmm:Artist .
<e> nmm:artistName "Cacophony" .
```
@@ -55,36 +60,44 @@ providing multiple objects (with `,` separator) or multiple
predicate/object pairs (with `;` separator), the previous RDF could be
transformed into:
-```
+```turtle
<a> a nfo:FileDataObject, nmm:MusicPiece .
<a> nie:title "Images" .
<a> nmm:musicAlbum <b> .
<a> nmm:albumArtist <c> , <d> .
<a> nmm:performer <e> .
+
<b> a nmm:MusicAlbum .
<b> nie:title "Go Off!" .
+
<c> a nmm:Artist .
<c> nmm:artistName "Jason Becker" .
+
<d> a nmm:Artist .
<d> nmm:artistName "Marty Friedman" .
+
<e> a nmm:Artist .
<e> nmm:artistName "Cacophony" .
```
And further into:
-```
+```turtle
<a> a nfo:FileDataObject, nmm:MusicPiece ;
nie:title "Images" ;
nmm:musicAlbum <b> ;
nmm:albumArtist <c>, <d> ;
nmm:performer <e> .
+
<b> a nmm:MusicAlbum ;
nie:title "Go Off!" .
+
<c> a nmm:Artist ;
nmm:artistName "Jason Becker" .
+
<d> a nmm:Artist ;
nmm:artistName "Marty Friedman" .
+
<e> a nmm:Artist ;
nmm:artistName "Cacophony" .
```
@@ -140,7 +153,7 @@ got unwieldly soon! Luckily, that is not necessarily the case, the
variables may be used anywhere in the triple definition, with other
triple elements consisting of literals you want to match for, e.g.:
-```
+```SPARQL
# Give me the title of resource <a> (Result: "Images")
SELECT ?songName { <a> nie:title ?songName }
```
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
