====================================================
 Validation et chargement dans GraphDB (13/10/2021)
====================================================

.. role:: en

Import des traces dans GraphDB
==============================

Dans cette partie du TP, notre objectif est de charger et valider votre trace dans une base de données RDF, que vous utiliserez également dans les prochains TPs. Pour cela, on vous fournira sur Tomuss l'adresse d'une machine virtuelle contenant une instance de GraphDB_.

.. _GraphDB: https://graphdb.ontotext.com/

.. admonition:: Votre travail

   * Depuis l'écran d'accueil de GraphDB (accessible sur ``http://ADDRESSE_SERVEUR:8080/``), sélectionnez *Setup > Repositories*.
   * Cliquez sur *Create new repository*.

   * Dans le formulaire qui s'affiche :

     - choisissez un nom (*Repository ID*) pour votre base,
     - dans *Ruleset*, sélectionnez « OWL2-RL (Optimized) »,
     - assurez vous que  la case *Disable owl:sameAs* n'est **pas** cochée,
     - cochez la case *Supports SHACL validation*,
     - puis cliquez sur *Create* en bas à gauche.

   * Pour charger vos données, sélectionnez *Import > RDF*:

     - cliquez sur *Upload RDF files*,
     - sélectionnez le fichier n-quads produit avec votre contexte JSON-LD,
     - une fois le fichier téléversé, cliquez sur le bouton *Import* en face    de son nom, et validez la boite de dialogue qui s'affiche sans changer    les options par défaut.

   * Vous pouvez enfin interroger votre base depuis l'écran *SPARQL*. Par    exemple, vous pouvez compter le nombre de tickets ouverts et fermés avec la    requête suivante ::

       PREFIX ex: <http://example.com/ns#>
       SELECT ?type (count(?issue) as ?nb_issues) {
         [] ex:issue ?issue. ?issue a ?type.
       } GROUP BY ?type

    Cette requête devrait donner un résultat de type:

    .. list-table::

      * - ``?type``
        - ``?nb_issues``
      * - ``owl:Thing``
        - 46
      * - ``ex:OpenIssue``
        - 12
      * - ``ex:ClosedIssue``
        - 34

.. hint:: 

    Vous pouvez également automatiser le chargement et l'interrogation des données grâce à l'API REST de GraphDB. Sa documentation est disponible depuis le menu *Help > REST API*.

SHACL: vérification de contraintes syntaxiques en RDF
=====================================================

Le premier rôle d'un modèle de traces est d'expliciter un certain nombre de contraintes que les données de la trace devraient respecter. La conformité au modèle permet de garantir une certaine homogénéité syntaxique et sémantique, indispensable pour assurer la robustesse des traitements ultérieurs de cette trace (transformation, analyse).

En RDF, ces contraintes syntaxiques sont exprimées grace au standard SHACL_ (`Shapes Constraint Language`:en:). Le principe est le suivant, illustré par la `fig-shacl`:numref:.

.. graphviz::
   :name: fig-shacl
   :caption: Processus de validation SHACL

   digraph {
     rankdir=LR;
     s [label="Shape\ngraph"]
     d [label="Data\ngraph"]
     p [label="SHACL\nprocessor"; shape=box]
     r [label="Validation\nreport"]

     s-> p
     d -> p
     p -> r
   }

* Les contraintes sont exprimées en RDF, en utilisant un vocabulaire spécifique à SHACL; un ensemble de contraintes à valider par un nœud ou un arc est appelé une **forme** (`shape`:en: en anglais).
* Le graphe décrivant les contraintes est appelé `Shapes graph`:en:.
* Le graphe à valider (celui qui doit satisfaire les contraintes) est appelé `Data graph`:en:.
* Un processeur SHACL prend ces deux graphes en entrée et produit en sortie un rapport indiquant :

  - si le `data graph`:en: vérifie oui ou non l'ensemble des contraintes du `shapes graph`:en:, et
  - dans la négative, la liste des violations constatées ;
  - ce rapport peut notamment être représenté par un graphe RDF, utilisant un vocabulaire spécifique à SHACL.

.. hint::

    Pour tester SHACL sur votre machine,
    une solution simple consiste à installer le package python `pySHACL`_
    qui fournit notamment un processeur SHACL en ligne de commande.

Modèle de traces github
+++++++++++++++++++++++

Pour la suite du TP, vous utiliserez le fichier `trace_model.shacl.ttl`_. Il est largement commenté, pour vous permettre

  * de découvrir par l'exemple les bases de SHACL, et
  * de comprendre quelles sont les contraintes imposées par le modèle de traces décrit lors de la séance précédente (`fig-modele`:numref:).

.. admonition:: Votre travail

    * Prendre connaissance de `trace_model.shacl.ttl`_.

    * Vérifier, à l'aide d'un valideur SHACL, que le contexte JSON-LD que vous avez élaboré à la séance précédente, produit un graphe conforme.

    * Le cas échéant, améliorer votre contexte JSON-LD pour générer une trace conforme.

Validation SHACL dans GraphDB
=============================

La base que vous avez créée dans GraphDB est un `dataset RDF`_. Elle contient un graphe par défaut (qui contient les triplets que vous y avez chargés), mais peut également contenir d'autres graphes (graphes nommés).

Le valideur SHACL intégré à GraphDB utilise cette fonctionnalité. Le `shapes graph`:en: doit être chargé dans un graphe nommé particulier, identifié par l'IRI http://rdf4j.org/schema/rdf4j#SHACLShapeGraph . Une fois ce graphe renseigné, GraphDB ne vous autorisera pas à modifier la base (ajout ou suppression de triplets) si le graphe résultant ne respecte pas les contraintes du `shapes graph`:en:.

Il existe plusieurs alternative pour remplir ce graphe.

* La première passe par l'écran *Import > RDF*, de la même manière que pour remplir le graphe par défaut employée ci-dessus. Mais dans la boite de dialogue de la dernière étape, cochez *Named graph* et saisir l'IRI http://rdf4j.org/schema/rdf4j#SHACLShapeGraph.

* La seconde utilise SPARQL, avec une requête du type::

    INSERT DATA {
      GRAPH <http://rdf4j.org/schema/rdf4j#SHACLShapeGraph> {
        #...
      }
    }

.. admonition:: Votre travail

    * Renseignez le `shapes graph`:en: de votre base avec le contenu de `trace_model.shacl.ttl`_.

    * Écrivez une requête SPARQL qui supprime tous les arcs ``s:identifier`` (ou n'importe quelle autre propriété requise sur une des `shapes`:en:). Constatez que GraphDB refuse d'exécuter cette requête.

    * Videz la base avec la requête SPARQL ``CLEAR ALL``. (NB: ceci ne vide *pas* le `shapes graph`:en:).

    * Créez une version modifiée de votre trace en RDF, dans laquelle un arc requis manque. Tentez d'importer ce fichier, et constatez que GraphDB refuse.

    * Reprenez la version correcte de votre trace en RDF, et importez là à nouveau. Constatez que GraphDB accepte (sous réserve, bien sûr, que votre trace remplisse toutes les contraintes).

.. _SHACL: https://www.w3.org/TR/shacl/
.. _pySHACL: https://github.com/RDFLib/pySHACL
.. _trace_model.shacl.ttl: _static/trace_model.shacl.ttl
.. _GraphDB: https://graphdb.ontotext.com/
.. _dataset RDF: https://www.w3.org/TR/rdf11-concepts/#h2_section-dataset