Document improvements to import and export functions

docs/_static/importexport_graph.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-09-15T15:00:07.279Z" agent="5.0 (X11)" etag="ol6Mp0m8xKfYCrX_vnMN" version="20.3.0" type="device"><diagram id="OcSXqWj7B0u8RQeyNCZC" name="Seite-1">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</diagram></mxfile>

docs/usage/ontologies/ontologies_included.md

@@ -25,6 +25,9 @@ domains of application, are listed below.
 - [](#the-prov-ontology-prov-o)
   \- Provenance information
 
+- [](#simple-knowledge-organization-system-skos)
+  \- Knowledge organization systems
+
 - [](#the-city-ontology)
   \- Example ontology aimed at demonstrating the usage of SimPhoNy
 
@@ -187,6 +190,25 @@ To install the [PROV-O ontology](https://www.w3.org/TR/prov-o/), use
 pico install prov
 ```
 
+## Simple Knowledge Organization System (SKOS)
+
+```{eval-rst}
+.. epigraph::
+
+   SKOS is an area of work developing specifications and standards to support
+   the use of knowledge organization systems (KOS) such as thesauri,
+   classification schemes, subject heading systems and taxonomies within the
+   framework of the Semantic Web.
+
+   -- `Introduction to SKOS <https://www.w3.org/2004/02/skos/intro>`_
+```
+
+To install [SKOS](https://www.w3.org/TR/2009/REC-skos-reference-20090818/), use
+
+```sh
+pico install skos
+```
+
 ## The City ontology
 
 The City ontology is a simple, example ontology included with SimPhoNy. It

docs/usage/sessions/import_export.ipynb

@@ -176,7 +176,7 @@
    "id": "afd633af-b85c-449b-94c7-2ff99a097150",
    "metadata": {},
    "source": [
-    "If instead, you wish to export all the contents of a session, then pass the session object to be exported."
+    "If instead, you wish to export all the individuals in a session, then pass the session object to be exported."
    ]
   },
   {
@@ -372,6 +372,118 @@
     "\n",
     "semantic2dot(session)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8b84a2b7-0bd9-4cf4-aa09-a1b2138ba43e",
+   "metadata": {},
+   "source": [
+    "## Interpretation of RDF files"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "81211841-d564-4974-b0a7-eef4982fa3e4",
+   "metadata": {},
+   "source": [
+    "The [ontology languages supported by SimPhoNy](../ontologies/supported_formats.md) can be serialized as RDF files, but the [RDF standard](https://www.w3.org/TR/rdf-concepts/) can store data that does not necessarily have anything to do with an ontology. Moreover, as described in the [introduction to sessions](introduction.ipynb), SimPhoNy sessions have been designed to exlusively store assertional knowledge (ontology individuals). \n",
+    "\n",
+    "Due to these factors, SimPhoNy enforces a few constraints when importing and exporting individuals from/to RDF files, that can, however, **also be disabled if desired**.\n",
+    "\n",
+    "1. No terminological knowledge can be present in the file. Any RDF triple with predicate `rdf:type` and one of `owl:Class`, `rdfs:Class`, `owl:AnnotationProperty`, `rdf:Property`, `owl:DatatypeProperty`, `owl:ObjectProperty`, `owl:Restriction` as object raises an exception.\n",
+    "\n",
+    "2. The subjects of any RDF triple with predicate `rdf:type` and an IRI not listed above as object are considered to be the identifiers of ontology individuals. Therefore, SymPhoNy will look into its installed ontologies for a class matching the object of the triple. If this lookup fails, an exception is raised. This behavior is meant to prevent you from making the mistake of importing data for which you have not installed the corresponding ontology.\n",
+    "\n",
+    "3. If an RDF triple where the subject has been succesfully identified as an ontology individual has a predicate different from `rdf:type` that cannot be recognized as an annotation, relationship nor an attribute, an exception will be raised.\n",
+    "\n",
+    "4. If an RDF triple where the subject has been succesfully identified as an ontology individual has a predicate that can be recognized as a relationship, but has an object that cannot be recognized as an ontology individual (for example, because no `rdf:type` has been defined for it), then an exception will be raised.\n",
+    "\n",
+    "5. If an RDF triple where the subject has been succesfully identified as an ontology individual has a predicate that can be recognized as a relationship, but has a literal as an object, an exception will be raised.\n",
+    "\n",
+    "6. If an RDF triple where the subject has been succesfully identified as an ontology individual has a predicate that can be recognized as an attribute, but has a IRI as an object, an exception will be raised.\n",
+    "\n",
+    "7. Any triples whose subject cannot be identified as terminological knowledge, as ontology individuals, or for which (2) does not apply are **not imported**. No warning nor exception of any kind is raised for such triples."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "97478c07-c469-4f64-b219-ff1d12e3b322",
+   "metadata": {},
+   "source": [
+    "<div class=\"admonition warning\">\n",
+    "<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Warning</div></div>\n",
+    "    \n",
+    "Point (7) implies that using the default options, you can lose data that was originally in the source, **without** warnings nor errors to notify you about it. Keep reading to learn how to prevent it. \n",
+    "    \n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "29fbacc8-3c05-4f4c-a7e2-f8836c1c7535",
+   "metadata": {},
+   "source": [
+    "There are two keyword arguments that can be passed to the import and export functions to bypass these checks.\n",
+    "\n",
+    "- `all_triples`: When set to `True`, no exceptions will be raised for points (2)*, (3), (4), (5), (6). Warnings will still be emitted.\n",
+    "- `all_statements`: When set to `True`, none of the points above apply. All RDF triples are imported, and **no information is lost**. No warnings are emitted."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e3208b1d-bc73-4a8c-a541-dd30f0a970f8",
+   "metadata": {},
+   "source": [
+    "<div class=\"admonition note\">\n",
+    "<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Note</div></div>\n",
+    "    \n",
+    "\\* To be recognized as an ontology individual, at least one of the types of the subject need to be defined in the [installed ontologies](../ontologies/pico.md). If you use `all_triples=True` when none of the types are defined in the installed ontologies, then (7) applies to such subject (its information is lost).\n",
+    "    \n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b15e4a71-b146-45da-9b55-e7306725dba0",
+   "metadata": {},
+   "source": [
+    "<div class=\"admonition warning\">\n",
+    "<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Warning</div></div>\n",
+    "    \n",
+    "Be careful when using `all_triples` and especially, when using `all_statements`. SimPhoNy's sessions have been designed to work only with ontology individuals. If you use `all_statements=True`, then also classes, relationships, annotations and attributes will be imported to the session, but as SimPhoNy is not ready to deal with this situation, this may lead to errors.\n",
+    "    \n",
+    "</div>\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "00cbc181-d4b3-4c12-847e-5b3c97f88579",
+   "metadata": {},
+   "source": [
+    "Below there is sample RDF graph that helps understanding all the cases."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96b841a5-80fa-4a9b-9a07-44bde08c31c0",
+   "metadata": {},
+   "source": [
+    "![Sample RDF graph exemplifying cases where the constraints above apply](../../_static/importexport_graph.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8a3156b-c999-4097-8478-b003f6a357f6",
+   "metadata": {},
+   "source": [
+    "1. The triple (`example:Skaters`, `rdf:type`, `owl:Class`) would trigger this case, because it defines terminological knowledge.\n",
+    "2. The triple (`example:Marco`, `rdf:type`, `foaf:Person`) matches this case, because the namespace `foaf` is not installed.\n",
+    "3. The triple (`example:Klaus`, `foaf:knows`, `example:Lena`) raises an exception, because the namespace `foaf` is not installed.\n",
+    "4. The triple (`example:Freiburg`, `city:hasInhabitant`, `example:Rob`) triggers this case, because `example:Rob` does not have any type assigned and therefore, it is not identified as an ontology individual.\n",
+    "5. The triple (`example:Freiburg`, `city:hasWorker`, `Lena (xsd:string)`) matches this case, as \"has worker\" is a relationship, but the object is a literal.\n",
+    "6. The triple (`example:Freiburg`, `city:coordinates`, `<geo:47.995,7.85>`) raises an exception, because \"coordinates\" is an attribute, but the object is an IRI.\n",
+    "7. The triple (`example:Something`, `example:predicate`, `example:Thing`) fits into this case."
+   ]
   }
  ],
  "metadata": {