From 5686f2f4d9f4aa15b321f09900f42aca72ac3af0 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Sun, 26 Mar 2023 11:07:45 +0200 Subject: docs: Improve NIE ontology introduction Explain more in depth the relation between dataobject/informationelement, taking inspiration from the original Nepomuk documentation in wording and illustrations. --- .../libtracker-sparql/images/containment.dot | 11 ++ .../libtracker-sparql/images/containment.svg | 37 +++++++ .../images/example-interpretation-containment.dot | 45 +++++++++ .../images/example-interpretation-containment.svg | 111 +++++++++++++++++++++ .../libtracker-sparql/images/interpretation.dot | 11 ++ .../libtracker-sparql/images/interpretation.svg | 37 +++++++ .../libtracker-sparql/nie-introduction.md | 65 +++++++----- .../libtracker-sparql/tracker-sparql.toml.in | 3 + 8 files changed, 295 insertions(+), 25 deletions(-) create mode 100644 docs/reference/libtracker-sparql/images/containment.dot create mode 100644 docs/reference/libtracker-sparql/images/containment.svg create mode 100644 docs/reference/libtracker-sparql/images/example-interpretation-containment.dot create mode 100644 docs/reference/libtracker-sparql/images/example-interpretation-containment.svg create mode 100644 docs/reference/libtracker-sparql/images/interpretation.dot create mode 100644 docs/reference/libtracker-sparql/images/interpretation.svg diff --git a/docs/reference/libtracker-sparql/images/containment.dot b/docs/reference/libtracker-sparql/images/containment.dot new file mode 100644 index 000000000..b668c7e11 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/containment.dot @@ -0,0 +1,11 @@ +digraph { + rankdir=LR; + bgcolor=transparent; + node [shape="box", style="filled,rounded",fontname="sans-serif", fixedsize=true,width=2]; + + "DataObject" [fillcolor="#ff000077"]; + "InformationElement" [fillcolor="#00ff0077"]; + + "DataObject":n -> "InformationElement":n [color="#777777ff",fontcolor="#777777ff",label="isPartOf",fontsize=10,fontname="sans-serif"]; + "InformationElement":s -> "DataObject":s [color="#777777ff",fontcolor="#777777ff",label="hasPart",fontsize=10,fontname="sans-serif"]; +} diff --git a/docs/reference/libtracker-sparql/images/containment.svg b/docs/reference/libtracker-sparql/images/containment.svg new file mode 100644 index 000000000..38788aead --- /dev/null +++ b/docs/reference/libtracker-sparql/images/containment.svg @@ -0,0 +1,37 @@ + + + + + + + + +DataObject + +DataObject + + + +InformationElement + +InformationElement + + + +DataObject:n->InformationElement:n + + +isPartOf + + + +InformationElement:s->DataObject:s + + +hasPart + + + diff --git a/docs/reference/libtracker-sparql/images/example-interpretation-containment.dot b/docs/reference/libtracker-sparql/images/example-interpretation-containment.dot new file mode 100644 index 000000000..f49fdd2be --- /dev/null +++ b/docs/reference/libtracker-sparql/images/example-interpretation-containment.dot @@ -0,0 +1,45 @@ +digraph { + rankdir=LR; + bgcolor=transparent; + node [shape="box", style="filled,rounded",fontname="sans-serif", fixedsize=true,width=2.5]; + + a [fillcolor="#ff000077",label="FileDataObject"]; + b [fillcolor="#ff000077",label="FileDataObject"]; + c [fillcolor="#ff000077",label="Attachment"]; + d [fillcolor="#ff000077",label="EmbeddedFileDataObject"]; + + a2 [fillcolor="#00ff0077",label="Folder"]; + b2 [fillcolor="#00ff0077",label="Document"]; + c2 [fillcolor="#00ff0077",label="Archive"]; + d2 [fillcolor="#00ff0077",label="Photo"]; + + subgraph cluster_do { + color=transparent; + label = "DataObject"; + fontname="sans-serif"; + fontsize=10; + a; + b; + c; + d; + } + + subgraph cluster_ie { + color=transparent; + label = "InformationElement"; + fontname="sans-serif"; + fontsize=10; + a2; + b2; + c2; + d2; + } + + a -> a2 [color="#777777ff",dir=back]; + a2 -> b:ne [color="#777777ff",dir=back]; + b -> b2 [color="#777777ff",dir=back]; + b2 -> c:ne [color="#777777ff",dir=back]; + c -> c2 [color="#777777ff",dir=back]; + c2 -> d:ne [color="#777777ff",dir=back]; + d -> d2 [color="#777777ff",dir=back]; +} diff --git a/docs/reference/libtracker-sparql/images/example-interpretation-containment.svg b/docs/reference/libtracker-sparql/images/example-interpretation-containment.svg new file mode 100644 index 000000000..8a7ba7c44 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/example-interpretation-containment.svg @@ -0,0 +1,111 @@ + + + + + + + +cluster_do + +DataObject + + +cluster_ie + +InformationElement + + + +a + +FileDataObject + + + +a2 + +Folder + + + +a->a2 + + + + + +b + +FileDataObject + + + +b2 + +Document + + + +b->b2 + + + + + +c + +Attachment + + + +c2 + +Archive + + + +c->c2 + + + + + +d + +EmbeddedFileDataObject + + + +d2 + +Photo + + + +d->d2 + + + + + +a2->b:ne + + + + + +b2->c:ne + + + + + +c2->d:ne + + + + + diff --git a/docs/reference/libtracker-sparql/images/interpretation.dot b/docs/reference/libtracker-sparql/images/interpretation.dot new file mode 100644 index 000000000..ba8378742 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/interpretation.dot @@ -0,0 +1,11 @@ +digraph { + rankdir=LR; + bgcolor=transparent; + node [shape="box", style="filled,rounded",fontname="sans-serif", fixedsize=true,width=2]; + + "DataObject" [fillcolor="#ff000077"]; + "InformationElement" [fillcolor="#00ff0077"]; + + "DataObject":n -> "InformationElement":n [color="#777777ff",fontcolor="#777777ff",label="interpretedAs",fontsize=10,fontname="sans-serif"]; + "InformationElement":s -> "DataObject":s [color="#777777ff",fontcolor="#777777ff",label="isStoredAs",fontsize=10,fontname="sans-serif"]; +} diff --git a/docs/reference/libtracker-sparql/images/interpretation.svg b/docs/reference/libtracker-sparql/images/interpretation.svg new file mode 100644 index 000000000..27931e5dd --- /dev/null +++ b/docs/reference/libtracker-sparql/images/interpretation.svg @@ -0,0 +1,37 @@ + + + + + + + + +DataObject + +DataObject + + + +InformationElement + +InformationElement + + + +DataObject:n->InformationElement:n + + +interpretedAs + + + +InformationElement:s->DataObject:s + + +isStoredAs + + + diff --git a/docs/reference/libtracker-sparql/nie-introduction.md b/docs/reference/libtracker-sparql/nie-introduction.md index f79535281..8d7478e7e 100644 --- a/docs/reference/libtracker-sparql/nie-introduction.md +++ b/docs/reference/libtracker-sparql/nie-introduction.md @@ -9,22 +9,33 @@ and content of a piece of data. Their specialized subclasses (defined in the other ontologies) can be used to classify a wide array of desktop resources and express them in RDF. -[nie:DataObject](nie-ontology.html#nie:DataObject) class represents a bunch of +[nie:DataObject](nie-ontology.html#nie:DataObject) class represents a collection of bytes somewhere (local or remote), the physical entity that contain -data. The *meaning* (interpretation) of that entity, the -information for the user contained in those bytes (e.g. a music file, +data. The *meaning* (interpretation) of that entity (e.g. a music file, a picture) is represented on the [nie:InformationElement](nie-ontology.html#nie:InformationElement) side of the ontology. -Both sides are linked using the -property [nie:interpretedAs](nie-ontology.html#nie:interpretedAs) (and its reverse -[nie:isStoredAs](nie-ontology.html#nie:isStoredAs)), indicating the correspondence -between the physical element and its interpretation. There is also a -property to -link [nie:InformationElement](nie-ontology.html#nie:InformationElement)s, -representing the logical containment between them (like a picture and -its album). +All resources on the desktop are basically related to each other with two most fundamental types +of relations: interpretation, Expressed through [nie:interpretedAs](nie-ontology.html#nie:interpretedAs) and its reverse +[nie:isStoredAs](nie-ontology.html#nie:isStoredAs). + +![](interpretation.svg) + +And containment, expressed through [nie:hasPart](nie-ontology.html#nie:hasPart) and its reverse +[nie:isPartOf](nie-ontology.html#nie:isPartOf). + +![](containment.svg) + +These properties (or their subproperties with a more specific semantic meaning) provide +the scaffolding to give an uniform view of the data with an arbitrary level of detail. +For a more thorough example, the figure below represents an image in an archive in the +attachment of a PDF document in the filesystem: + +![](example-interpretation-containment.svg) + +The horizontal edges express interpretation, the diagonal edges express containment. +This approach gives a uniform overview of data regardless of how it's represented. ## Common properties @@ -57,26 +68,30 @@ One of the most common resources in a desktop is a file. Given the split between 1. Every file (local or remote) should generate one DataObject instance and an InformationElement instance. 2. Even when Data Objects and Information Elements are different entities. 3. The URI of the DataObject is the real location of the item (e.g. ''file://path/to/file.mp3'') - 3. The URI of the InformationElement(s) will be autogenerated IDs. + 3. The URI of the InformationElement(s) will be generated IDs. 4. Every DataObject must have the property [nie:url](nie-ontology.html#nie:url), that points to the location of the resource, and should be used by any program that wants to access it. - 5. The InformationElement and DataObject are related via the nie:isStoredAs / nie:interpretedAs properties. + 5. The InformationElement and DataObject are related via the [nie:isStoredAs](nie-ontology.html#nie:isStoredAs) / [nie:interpretedAs](nie-ontology.html#nie:interpretedAs) properties. -Here comes an example, for the image file /home/user/a.jpeg: +Here comes an example, for the image file `/home/user/a.jpeg`: -``` +```turtle # Properties as nmm:Photo a nmm:Photo ; - nie:isStoredAs ; - nfo:width 49 ; - nfo:height 36 ; - nmm:flash <nmm:flash-off>; - nmm:whiteBalance ; - nfo:equipment [ a nfo:Equipment ; nfo:make 'Nokia'; nfo:model 'N900'; nfo:equipmentSoftware 'Tracknon' ] . + nie:isStoredAs ; + nfo:width 49 ; + nfo:height 36 ; + nmm:flash nmm:flash-off; + nmm:whiteBalance nmm:white-balance-automatic ; + nfo:equipment [ + a nfo:Equipment ; + nfo:make 'Nokia'; + nfo:model 'N900'; + nfo:equipmentSoftware 'Tracknon' + ] . # Properties from nfo:FileDataObject a nfo:FileDataObject ; - nie:interpretedAs ; - nfo:fileSize 12341234 ; - # Mandatory for any nfo:DataObject - nie:url . + nie:interpretedAs ; + nfo:fileSize 12341234 ; + nie:url 'file:///home/user/a.jpeg' . ``` diff --git a/docs/reference/libtracker-sparql/tracker-sparql.toml.in b/docs/reference/libtracker-sparql/tracker-sparql.toml.in index ceae430d3..6739e6714 100644 --- a/docs/reference/libtracker-sparql/tracker-sparql.toml.in +++ b/docs/reference/libtracker-sparql/tracker-sparql.toml.in @@ -36,6 +36,9 @@ content_files = [ ] content_images = [ "logo.svg", + "images/interpretation.svg", + "images/containment.svg", + "images/example-interpretation-containment.svg", ] urlmap_file = "urlmap.js" -- cgit v1.2.1