1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
|
<!DOCTYPE html>
<html lang="en">
<head>
<base href=".">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Defining ontologies</title>
<link rel="stylesheet" href="assets/css/custom_bootstrap.css" type="text/css">
<link rel="stylesheet" href="assets/css/bootstrap-toc.min.css" type="text/css">
<link rel="stylesheet" href="assets/css/frontend.css" type="text/css">
<link rel="stylesheet" href="assets/css/jquery.mCustomScrollbar.min.css">
<link rel="stylesheet" href="assets/js/search/enable_search.css" type="text/css">
<link rel="stylesheet" href="assets/css/tracker-custom.css" type="text/css">
<link rel="stylesheet" href="assets/css/prism.css" type="text/css">
<link rel="stylesheet" href="assets/css/devhelp.css" type="text/css">
<script src="assets/js/mustache.min.js"></script>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/bootstrap.js"></script>
<script src="assets/js/scrollspy.js"></script>
<script src="assets/js/typeahead.jquery.min.js"></script>
<script src="assets/js/search.js"></script>
<script src="assets/js/compare-versions.js"></script>
<script src="assets/js/jquery.mCustomScrollbar.concat.min.js"></script>
<script src="assets/js/bootstrap-toc.min.js"></script>
<script src="assets/js/jquery.touchSwipe.min.js"></script>
<script src="assets/js/anchor.min.js"></script>
<script src="assets/js/tag_filtering.js"></script>
<script src="assets/js/language_switching.js"></script>
<script src="assets/js/lines_around_headings.js"></script>
<script src="assets/js/prism-core.js"></script>
<script src="assets/js/prism-autoloader.js"></script>
<script src="assets/js/prism_autoloader_path_override.js"></script>
<script src="assets/js/trie.js"></script>
</head>
<body class="no-script
">
<script>
$('body').removeClass('no-script');
</script>
<nav class="navbar navbar-fixed-top navbar-default" id="topnav">
<div class="container-fluid">
<div class="navbar-right">
<a id="toc-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-wrapper" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<form class="navbar-form pull-right" id="navbar-search-form">
<div class="form-group has-feedback">
<input type="text" class="form-control input-sm" name="search" id="sidenav-lookup-field" placeholder="search" disabled>
<span class="glyphicon glyphicon-search form-control-feedback" id="search-mgn-glass"></span>
</div>
</form>
</div>
<div class="navbar-header">
<a id="sidenav-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<a id="home-link" href="index.html" class="hotdoc-navbar-brand">
<img src="assets/images/home.svg" alt="Home">
</a>
</div>
<div class="navbar-collapse collapse" id="navbar-wrapper">
<ul class="nav navbar-nav" id="menu">
<li>
<a href="https://gnome.pages.gitlab.gnome.org/tracker/">Website</a>
</li>
</ul>
<div class="hidden-xs hidden-sm navbar-text navbar-center">
</div>
</div>
</div>
</nav>
<main>
<div data-extension="core" data-hotdoc-in-toplevel="True" data-hotdoc-project="Tracker" data-hotdoc-ref="defining-ontologies.html" class="page_container" id="page-wrapper" data-hotdoc-meta-gi-languages="['c', 'javascript', 'python']">
<script src="assets/js/utils.js"></script>
<div class="panel panel-collapse oc-collapsed" id="sidenav" data-hotdoc-role="navigation">
<script src="assets/js/navigation.js"></script>
<script src="assets/js/sitemap.js"></script>
</div>
<div id="body">
<div id="main">
<div id="page-description" data-hotdoc-role="main">
<h1 id="defining-ontologies">Defining ontologies</h1>
<p>An ontology defines the entities that a Tracker endpoint can store, as
well as their properties and the relationships between different entities.</p>
<p>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:</p>
<ul>
<li>XML Schema (XSD), defining basic types</li>
<li>Resource Description Framework (RDF), defining classes, properties and
inheritance</li>
<li>Nepomuk Resource Language (NRL), defining resource uniqueness, inheritance
and indexes.</li>
<li>Dublin Core (DC), defining common superproperties for documents</li>
</ul>
<p>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.</p>
<p>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.</p>
<h2 id="creating-an-ontology">Creating an ontology</h2>
<h3 id="defining-a-namespace">Defining a namespace</h3>
<p>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:</p>
<pre><code class="language-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"
</code></pre>
<h3 id="defining-classes">Defining classes</h3>
<p>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:</p>
<pre><code class="language-turtle">ex:Eukaryote a rdfs:Class;
rdfs:subClassOf rdfs:Resource;
rdfs:comment "An eukaryote".
</code></pre>
<p>By convention all classes use CamelCase names, although class names
are not restricted. The allowed charset is UTF-8.</p>
<p>Declaring subclasses is possible:</p>
<pre><code class="language-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".
</code></pre>
<p>With such classes defined, resources may be inserted to the endpoint,
eg. with the SPARQL:</p>
<pre><code class="language-SPARQL">INSERT DATA { <merry> a ex:Mammal }
INSERT DATA { <treebeard> a ex:Animal, ex:Plant }
</code></pre>
<p>Note that multiple inheritance is possible, resources will just inherit
all properties from all classes and superclasses.</p>
<h3 id="defining-properties">Defining properties</h3>
<p>Properties relate to a class, so all resources pertaining to that class
can define values for these.</p>
<pre><code class="language-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;
</code></pre>
<p>The class the property belongs to is defined by <code>rdfs:domain</code>, while the
data type contained is defined by <code>rdfs:range</code>. By convention all
properties use dromedaryCase names, although property names are not
restricted. The allowed charset is UTF-8.</p>
<p>The following basic types are supported:</p>
<ul>
<li><code>xsd:boolean</code></li>
<li>
<code>xsd:string</code> and <code>rdf:langString</code>
</li>
<li>
<code>xsd:integer</code>, ranging from -2^63 to 2^63-1.</li>
<li>
<code>xsd:double</code>, able to store a 8 byte IEEE floating point number.</li>
<li>
<code>xsd:date</code> and <code>xsd:dateTime</code>, able to store dates and times since
January 1st 1 AD, with microsecond resolution.</li>
</ul>
<p>Of course, properties can also point to resources of the same or
other classes, so stored resources can conform a graph:</p>
<pre><code class="language-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;
</code></pre>
<p>There is also inheritance of properties, an example would be a property
in a subclass concretizing a more generic property from a superclass.</p>
<pre><code class="language-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.
</code></pre>
<p>SPARQL queries are expected to provide the same result when queried
for a property or one of its superproperties.</p>
<pre><code class="language-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" }
</code></pre>
<h3 id="defining-cardinality-of-properties">Defining cardinality of properties</h3>
<p>By default, properties are multivalued, there are no restrictions in
the number of values a property can store.</p>
<pre><code class="language-SPARQL">INSERT DATA {
<cat> a ex:Mammal .
<dog> a ex:Mammal .
<peter> a ex:Mammal ;
ex:pets <cat>, <dog>
}
</code></pre>
<p>Wherever this is not desirable, cardinality can be limited on properties
through nrl:maxCardinality.</p>
<pre><code class="language-turtle">ex:cromosomes a rdf:Property;
rdfs:domain ex:Eukaryote;
rdfs:range xsd:integer;
nrl:maxCardinality 1.
</code></pre>
<p>This will raise an error if the SPARQL updates in the endpoint end up
in the property inserted multiple times.</p>
<pre><code class="language-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 }
</code></pre>
<p>Tracker does not implement support for other maximum cardinalities
than 1.</p>
<!---
XXX: explain how cardinality affects subproperties, superproperties
--->
<h3 id="defining-uniqueness">Defining uniqueness</h3>
<p>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.</p>
<pre><code class="language-turtle">ex:geneticInformation a rdf:Property, nrl:InverseFunctionalProperty;
rdfs:domain ex:Eukaryote;
rdfs:range xsd:string;
</code></pre>
<p>With that in place, no two resources can have the same value on the
property.</p>
<pre><code class="language-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" }
</code></pre>
<!---
XXX: explain how inverse functional proeprties affect sub/superproperties
--->
<h3 id="defining-indexes">Defining indexes</h3>
<p>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:</p>
<pre><code class="language-turtle"># Make queries on ex:dateOfBirth faster
ex:Mammal a rdfs:Class;
rdfs:subClassOf ex:Animal;
rdfs:comment "A mammal";
nrl:domainIndex ex:dateOfBirth.
</code></pre>
<p>Classes may define multiple domain indexes.</p>
<p><strong>Note</strong>: 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.</p>
<h3 id="defining-fulltext-search-properties">Defining full-text search properties</h3>
<p>Tracker provides nonstandard full-text search capabilities, in order to use
these, the string properties can use nrl:fulltextIndexed:</p>
<pre><code class="language-turtle">ex:name a rdf:Property;
rdfs:domain ex:Mammal;
rdfs:range xsd:string;
nrl:fulltextIndexed true;
nrl:weight 10.
</code></pre>
<p>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:</p>
<pre><code class="language-SPARQL">SELECT { ?mammal a ex:Mammal;
fts:match "timmy" }
</code></pre>
<h3 id="predefined-elements">Predefined elements</h3>
<p>It may be desirable for the ontology to offer predefined elements of a
certain class, which can then be used by the endpoint.</p>
<pre><code class="language-turtle">ex:self a ex:Mammal.
</code></pre>
<p>Usage does not differ in use from the elements of that same class that
could be inserted in the endpoint.</p>
<pre><code class="language-SPARQL">INSERT DATA { ex:self ex:pets <cat> .
<cat> ex:pets ex:self }
</code></pre>
<h3 id="accompanying-metadata">Accompanying metadata</h3>
<p>Ontology files are optionally accompanied by description files, those have
the same basename, but the ".description" extension.</p>
<pre><code class="language-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".
</code></pre>
<h2 id="updating-an-ontology">Updating an ontology</h2>
<p>As software evolves, sometimes changes in the ontology are unavoidable.
Tracker can transparently handle certain ontology changes on existing
databases.</p>
<ol>
<li>
<p>Adding a class.</p>
</li>
<li>
<p>Removing a class.
All resources will be removed from this class, and all related
properties will disappear.</p>
</li>
<li>
<p>Adding a property.</p>
</li>
<li>
<p>Removing a property.
The property will disappear from all elements pertaining to the
class in domain of the property.</p>
</li>
<li>
<p>Changing rdfs:range of a property.
The following conversions are allowed:</p>
<ul>
<li>
<code>xsd:integer</code> to <code>xsd:bool</code>, <code>xsd:double</code> and <code>xsd:string</code>
</li>
<li>
<code>xsd:double</code> to <code>xsd:bool</code>, <code>xsd:integer</code> and <code>xsd:string</code>
</li>
<li>
<code>xsd:string</code> to <code>xsd:bool</code>, <code>xsd:integer</code> and <code>xsd:double</code>
</li>
</ul>
</li>
<li>
<p>Adding and removing <code>nrl:domainIndex</code> from a class.</p>
</li>
<li>
<p>Adding and removing <code>nrl:fulltextIndexed</code> from a property.</p>
</li>
<li>
<p>Changing the <code>nrl:weight</code> on a property.</p>
</li>
<li>
<p>Removing <code>nrl:maxCardinality</code> from a property.</p>
</li>
</ol>
<!---
XXX: these need documenting too
add intermediate superproperties
add intermediate superclasses
remove intermediate superproperties
remove intermediate superclasses
--->
<p>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:</p>
<ul>
<li>Properties with rdfs:range being <code>xsd:bool</code>, <code>xsd:date</code>, <code>xsd:dateTime</code>,
or any other custom class are not convertible. Only conversions
covered in the list above are accepted.</li>
<li>You can not add <code>rdfs:subClassOf</code> in classes that are not being
newly added. You can not remove <code>rdfs:subClassOf</code> from classes.
The only allowed change to <code>rdfs:subClassOf</code> is to correct
subclasses when deleting a class, so they point a common
superclass.</li>
<li>You can not add <code>rdfs:subPropertyOf</code> to properties that are not
being newly added. You can not change an existing
<code>rdfs:subPropertyOf</code> unless it is made to point to a common
superproperty. You can however remove <code>rdfs:subPropertyOf</code> from
non-new properties.</li>
<li>Properties can not move across classes, thus any change in
<code>rdfs:domain</code> is forbidden.</li>
<li>You can not add <code>nrl:maxCardinality</code> restrictions on properties that
are not being newly added.</li>
<li>You can not add nor remove <code>nrl:InverseFunctionalProperty</code> from a
property that is not being newly added.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Once changes are made, the nrl:lastModified value should be updated
so Tracker knows to reprocess the ontology.</p>
</div>
</div>
<div id="search_results">
<p>The results of the search are</p>
</div>
<div id="footer">
</div>
</div>
<div id="toc-column">
<div class="edit-button">
</div>
<div id="toc-wrapper">
<nav id="toc"></nav>
</div>
</div>
</div>
</main>
<script src="assets/js/navbar_offset_scroller.js"></script>
</body>
</html>
|
