Import de la trace brute (06/10/2021)

Trace brute

La trace brute que nous nous proposons d’étudier ici est fournie par l”API de github, plus précisément la partie qui permet de récupérer les tickets (issues) et leurs commentaires.

Pour vous faire gagner du temps, un script python vous est fourni, qui permet de récupérer tous les tickets et tous les commentaires d’un dépôt. Ce script accepte les arguments suivants :

  • Un argument obligatoire donnant le nom du dépôt, sous la forme owner/repo (par exemple, pchampin/sophia_rs pour le dépôt https://github.com/pchampin/sophia_rs).

  • L’argument optionnel --out indique dans quel fichier écrire les données récupérées. Attention: si le fichier existe déjà, son contenu sera remplacé. Si cet argument n’es pas spécifié, les données seront écrites sur la sortie standard.

  • L’argument optionnel --prev permet de spécifier le chemin d’un fichier précédemment produit par le script, pour le même dépôt. Le script interrogera alors l’API de github de telle manière à ne récupérer que les éléments plus récents que ceux ayant déjà été récupérés.

  • L’argument optionnel --auth permet de spécifier un jeton d’authentification github, qui peut être créé sur https://github.com/settings/tokens.

Avertissement

Il n’est pas nécessaire de créer un jeton d’authentification pour utiliser l’API. Notez cependant que l’API est soumise à des quotas (nombre limité d’appels par heure) et que ces quotas sont plus importants pour les utilisateurs authentifiés.

Quoi qu’il en soit, que vous ayez ou non un jeton d’authentification, il faut donc utiliser l’API github (et donc le script qui vous est fourni) avec parcimonie, pour ne pas saturer vos quotas. Stockez le JSON obtenu dans un fichier, et travaillez ensuite sur ce fichier local.

Le fichier JSON produit par ce script contient un tableau d’objets JSON ; les objets du début du tableau représentent les tickets, ceux de la fin du tableau représentent les commentaires.

Votre travail

Choisissez un dépôt github, et récupérez à l’aide du script fourni un fichier JSON contenant tous les tickets et commentaires de ce dépôt.

Modèle de traces

On souhaite convertir la trace brute (JSON) récupérée en une trace modélisée en RDF, conforme au modèle de traces décrit dans la Fig. 1.

_images/trace_model.svg

Fig. 1 Modèle de traces pour les tickets et les commentaires

Ce diagramme de classe décrit les entités que nous souhaitons représenter, avec leurs propriétés et les relations qu’elles entretiennent. Quelques précisions sont nécessaires.

  • Le préfixe s: correspond à l’IRI http://schema.org/ (un vocabulaire standard que nous réutilisons autant que possible).

  • Le préfixe ex: correspond à l’IRI http://exampe.com/ns# (un vocabulaire imaginaire qui nous permet de décrire les concepts non présents dans Schema.org).

  • En plus des classes Issue et Comment, on voit que le modèle de traces inclut des entités supplémentaires (Repository, User, Label). En effet, ces entités sont utiles pour représenter l’activité, et elles sont également décrites dans le JSON de la trace brute (comme attributs des tickets et des commentaires).

    • Notons cependant que seules Issue (et ses sous-classes) et Comment ont le statut d”obsel, puisque seules ces entités sont horodatées.

    • Ces entités supplémentaires sont décrites plusieurs fois dans le JSON (notamment les utilisateurs et les labels). Cette redondance n’est pas gênante puisque, dans le graphe RDF, les arcs identiques ne sont pris en compte qu’une seule fois.

  • Pour identifier les entités dans notre graphe RDF, on choisit l’IRI qui les identifie dans l’API de github (attribut url dans le JSON).

    • Par contraste, la propriété s:url sera utilisée pour pointer vers la représentation HTML de l’entité (attribut html_url dans le JSON).

  • Les identifiants internes (attribut id) utilisés par github ne nous intéressent pas. La propriété s:accountId de la classe User correspond au login de l’utilisateur concerné ; la propriété s:identifier de la classe Issue correspond au numéro de ticket (attribut number).

  • Les classes dont le nom est entre parenthèses ne sont pas matérialisées dans le graphe RDF, et donc leurs instances n’auront pas de propriété rdf:type explicite indiquant qu’elles appartiennent à cette classe.

Votre travail

Écrire

  • un contexte JSON-LD qui, associé au JSON retourné par l’API de github, permet de produire un graphe conforme au modèle ci-dessus, et

  • un programme qui utilise une bibliothèque JSON-LD pour appliquer ce contexte et produire le graph RDF au format n-quads.

Indication

Une liste de bibliothèque implémentant JSON-LD est disponible sur https://json-ld.org/#developers.

Pour développer (expand) ou convertir en RDF un document JSON natif, la meilleure solution consiste à fournir le contexte séparément, via l’option expandContext des algorithmes.

NB: en PyLD, les options sont passées via un dictionnaire:

jsonld.to_rdf(raw_doc, {
    'expandContext': ctx,  # contexte à appliquer
    'format': 'application/n-quads', # format de sortie
}))