Creazione e gestione dei repository per le risorse semantiche¶

Considerato il funzionamento di harvesting di Schema, ovvero il processo di acquisizione dei contenuti semantici e conseguente caricamento sul Catalogo (rif. Raccolta e memorizzazione dei dati semantici) è necessario che ogni Contributore crei o abbia già a disposizione un repository da cui esporre le proprie risorse semantiche che saranno, quindi, raccolte in schema.gov.it come descritto nel manuale operativo.

Quando chiedere semantic stewardship ad Istat¶

In qualità di Soggetto Attuatore del Progetto, l’Istat offre alle pubbliche amministrazioni interessate a pubblicare risorse semantiche nel Catalogo, una semantic stewardship finalizzata alla creazione di risorse in linea con i propri standard. In questo caso, il Contributore sceglie di affidare all’Istat l’analisi concettuale del proprio dominio di interesse e la conseguente rappresentazione in modelli di dati oppure definire concettualmente, secondo quanto indicato in La semantica dei dati della PA e Scopo del Catalogo. la semantica del proprio dominio e richiedere la modellazione ontologica e/o la definizione di vocabolari controllati e/o la definizione di schemi dati.

Tale modalità è da scegliere nel caso in cui il Contributore abbia necessità di supporto per la creazione delle risorse semantiche relative ai propri dati. In questo caso, il Contributore si interfaccerà direttamente con l’Istat al fine di individuare i contenuti da pubblicare sul Catalogo; le attività di strutturazione sintattica e semantica dei contenuti saranno curate da l’Istat, col supporto del Contributore. Il Contributore, in quanto responsabile dei contenuti semantici relativi ai propri dati, dovrà approvare, nel caso di ontologie, le definizioni dei concetti e delle loro relazioni, mentre, nel caso di vocabolari controllati, dovrà fornire la classificazione ed eventualmente la sua gerarchia nel caso di vocabolari più articolati in un formato strutturato (ad esempio, in file .csv) che riporti: il livello di gerarchia, la relazione gerarchica padre-figlio, la codifica, il lemma e la descrizione delle singole voci di classificazione in italiano, in inglese e in altre lingue se necessario per i fini del dominio in oggetto. Invece, nel caso di un e-service, dovrà fornire documentazione descrittiva del servizio e nello specifico dell’input e dell’output dello stesso.

Riguardo all’individuazione del dominio degli URI e del repository, il Contributore sarà supportato dall’Istat nella scelta tra le alternative descritte in Scelta degli identificativi univoci nel web.

Aggiunta di nuove risorse¶

Di seguito il dettaglio delle attività propedeutiche del Contributore per l’aggiunta di nuove risorse sul Catalogo:

• Se vuoi registrare URI sotto il w3id.org/italia:

  • Nel caso in cui si abbiano a disposizione risorse da pubblicare caratterizzate da un elevato livello di generalità e riutilizzabilità su scala nazionale, allora si potranno registrare URI sotto w3id.org/italia, beneficiando dei meccanismi di URI dereferentiation e Content Negotiation già implementate. A tale scopo, fai riferimento alle istruzioni contenute nel repository Italia e alle indicazioni rese disponibili nel manuale operativo su come modellare e metadatare le risorse.

  • Nel caso in cui le risorse da pubblicare non siano caratterizzate da un elevato livello di generalità e riutilizzabilità su scala nazionale, allora si potranno registrare URI sotto w3id.org/italia/<dominio_specifico>. In tal caso, le istruzioni sono le seguenti:

    • Per la modellazione e metadatazione, fai riferimento alle indicazioni differenziate per tipologia di risorsa (vocabolario controllato, ontologia o schema dati) contenute nel manuale operativo;
    • Per la predisposizione del repository, fai riferimento alle indicazioni riguardo la struttura del repository da creare e che verrà registrato tra le sorgenti del Catalogo. I file richiesti, il versionamento e ulteriori dettagli sulle risorse semantiche sono contenute nel manuale operativo;
    • Per l’implementazione del redirect degli URI stabili, fai riferimento alla soluzione descritta nel manuale operativo;
    • Per il test dei requisiti tecnici per l’harvesting delle risorse semantiche, fermo restando che il Contributore è responsabile dei contenuti pubblicati nel proprio repository, è necessario verificare che le risorse semantiche soddisfino i requisiti tecnici richiesti per l’avvio della fase di harvesting da parte del Catalogo. Per supportare al meglio i Contributori in tale processo, gli Amministratori del Catalogo sono al lavoro su una pagina web “Strumenti di validazione”, che suggerirà per ciascun use-case il validatore più consono da poter utilizzare. In particolare, (i) per i file index.ttl degli schemi dati e per le ontologie verrà indicato il validatore in fase di sviluppo da parte degli Amministratori del Catalogo; (ii) per i vocabolari controllati si potrà utilizzare il validatore DCAT-AP_IT sviluppato da AGID ignorando eventuali warning ed errori sulla presenza della classe dcatapit:Catalog e sull’uso della proprietà owl:versionInfo quando più lingue vengono specificate per la proprietà. In aggiunta, verrà indicato il validatore delle OpenAPI (Italian API Guidelines Checker), ovvero per i file .yaml. I controlli implementati dal validatore, attualmente in sviluppo da parte degli Amministratori, saranno un sottoinsieme di quelli eseguiti in fase di harvesting dalla piattaforma Catalogo; in particolare, i controlli verificheranno la presenza dei metadati mandatori nel file turtle e la validità dei prefissi rispetto alle relative ontologie. Infine, per un test di visualizzazione e di correttezza delle risorse semantiche rispetto ai requisiti tecnici per l’harvesting espressi nel manuale operativo, è possibile richiedere, utilizzando la mail info@schema.gov.it, un primo aggiornamento nell’ambiente di test del Catalogo e, al termine della fase di test, richiedere l’harvesting in produzione.

• Se vuoi registrare URI in domini come w3id.org/<dominio_specifico>:

  • Segui le istruzioni contenute nell’elenco al punto precedente. Per l’attività di implementazione del redirect su URI stabili, puoi far riferimento alla guida ufficiale pubblicata dal w3id. Inoltre, per la creazione dei file di configurazione del redirect, puoi considerare a titolo esemplificativo le istruzioni contenute nel manuale operativo.

• Se vuoi registrare URI in domini proprietari:

  • Segui autonomamente tutte le specifiche richieste.

• Se vuoi chiedere semantic stewardship a Istat:

  • Invia una richiesta di contribuzione al Catalogo utilizzando la mail info@schema.gov.it.

Richiesta di modifica di risorse già in Catalogo¶

Se vuoi suggerire una modifica a un contenuto semantico già esistente nel Catalogo, fai riferimento al manuale operativo.

Ontologia¶

La scheda di dettaglio di un’ontologia fornisce informazioni quali il titolo, la descrizione, e mostra due tasti che permettono di accedere alle due funzionalità SPARQL e Vai al sorgente.

Esempio schermata della scheda di un’ontologia

In particolare:

• Il tasto SPARQL permette di accedere all”endpoint SPARQL ed effettuare interrogazioni sull’ontologia, interagendo col Graph Store del Catalogo.

Interfaccia per l’esecuzione di interrogazioni mediante SPARQL Query Editor

• Il tasto Vai al sorgente permette di accedere al repository sorgente della risorsa semantica, dove eventualmente l’utente può aprire nuove issue.

Nella scheda della risorsa è presente anche una tabella che contiene i dettagli dell’ontologia. Tra i vari elementi cliccabili in tabella vi è il campo URI, che permette di accedere al visualizzatore lode - un visualizzatore HTML di ontologie espresse in RDFS e OWL - dove l’utente ha la possibilità di esaminare varie caratteristiche dell’ontologia, tra cui le classi, le proprietà, nonché informazioni di carattere generale quali la versione corrente, gli autori e altre modalità di visualizzazione.

Esempio visualizzatore lode di un’ontologia

Vocabolario controllato¶

La scheda di dettaglio dei vocabolari controllati contiene pressoché gli stessi elementi descritti per le ontologie.

Esempio schermata della scheda di un vocabolario controllato

Per i vocabolari controllati è presente un tasto aggiuntivo, API, che permette di accedere alla Swagger UI e quindi fruire del vocabolario controllato tramite un’apposita API.

Interfaccia Swagger UI per vocabolario controllato

Anche in questo caso, è presente una tabella che contiene i dettagli della risorsa semantica, con un importante differenza: il campo URI rimanda non più al visualizzatore lode, bensì lodview - un software aperto di dereferenziazione di URI che consente di navigare i dati via Web - dove l’utente ha la possibilità di esaminare varie caratteristiche del vocabolario controllato correlate al linguaggio RDF.

Esempio visualizzatore lodview di un vocabolario controllato

Schema¶

La scheda di dettaglio per gli schemi dati mostra il titolo, la descrizione e il tasto Vai al sorgente con funzionamento analogo a quello descritto per ontologie e vocabolari controllati.

In aggiunta, è presente una tabella che contiene, oltre alle informazioni di base della risorsa, una visualizzazione Swagger UI completamente integrata, e che abilita la fruizione dello schema dati mediante la visualizzazione estesa dei vari campi della sezione schemas.

Esempio di tabella contenuta in una scheda per gli schemi dati

Richiesta di aggiornamento di asset semantici esistenti¶

A partire dalla scheda di dettaglio di qualsiasi asset semantico nel Catalogo, è possibile cliccare su un tasto Vai al sorgente per essere indirizzati sul repository git che contiene i dati su cui è stato effettuato l’harvesting. In tal modo, è possibile non solo consultare i codici sorgenti delle risorse semantiche, ma anche aprire eventuali issue nel caso in cui siano stati rilevati errori sui relativi contenuti semantici.

Nel caso di richiesta di integrazioni, il Contributore o l’utente che apre la issue dovrà fare riferimento alle indicazioni tecniche fornite nel manuale operativo.

Introduzione al redirect con w3id.org¶

w3id.org è una soluzione del W3C Permanent Identifier Community Group che permette l’aggiunta o modifica di identificativi permanenti a partire dai quali reindirizzare verso URL specifici; il processo si basa sull’aggiunta di una o più cartelle nel repository git del w3id le quali contengono i file .htaccess e file README.md, eventualmente organizzati in sottocartelle.

Nel caso del Catalogo si può richiedere la registrazione di un proprio dominio su w3id creando una cartella dedicata oppure facendo riferimento alla cartella Italia del GIT del w3id, nella quale possono essere aggiunte le sottocartelle, ciascuna per una particolare area tematica, contenenti i file di reindirizzamento, eventualmente organizzati in ulteriori sottocartelle, ed il file README.md; successivamente, le stesse saranno gestite autonomamente e con interfacciamento diretto verso w3id.org dai referenti indicati nei file README.md. La cartella e le relative sottocartelle, i file .htaccess e i file README.md sono creati sul repository git del w3id dal Contributore.

Una nota importante è che l’efficacia delle regole di redirect descritte nei seguenti paragrafi è subordinata all’applicazione delle indicazioni offerte dalla presente guida per la creazione ed organizzazione del repository contenente le risorse semantiche, con particolare riferimento all’uguaglianza che deve persistere tra il nome di ciascuna cartella e il nome dei relativi file, a meno dell’estensione, e il nome con il quale viene referenziata la risorsa semantica (ontologia) all’interno del proprio URI.

Processo di pubblicazione degli htaccess¶

italia
|--nome-cartella
|  |--controlled-vocabulary
|  |  |-.htaccess
|  |--data
|  |  |-.htaccess
|  |--onto
|  |  |-.htaccess
|  |README.md

Contenuto dei file htaccess e readme¶

Di seguito è data una descrizione del file .htaccess per ciascuna tipologia di risorsa, da cui il Contributore può prendere spunto per creare i propri file di redirect. Gli esempi sono calati nella casistica in cui il Contributore voglia iscrivere le proprie URI sotto w3id.org/italia/<dominio_specifico>, voglia fruire delle soluzioni di URI dereferentiation implementate in Schema, e abbia rispettato le indicazioni sulla creazione del repository sorgente per le proprie risorse semantiche descritte in Istruzioni su come predisporre il repository. In casi diversi rispetto al precedente, il Contributore dovrà adeguare opportunamente le regole di redirect descritte di seguito.

Header set Access-Control-Allow-Origin *

Options +FollowSymLinks

RewriteEngine on

SetEnvIf Accept ^.*text/turtle.* SYNTAX=ttl

SetEnvIf Accept ^.*application/json.* SYNTAX=json

SetEnvIf Accept ^.*application/csv.* SYNTAX=csv

SetEnvIf Accept ^.*text/csv.* SYNTAX=csv

SetEnvIf Accept ^.*text/html.* SYNTAX=html

SetEnvIf Request_URI ^.*$ ROOT_URL=<url-git>

RewriteCond %{ENV:SYNTAX} ^(ttl|json|csv)$

RewriteRule ^([a-zA-Z-_0-9]+)(/?)$ %{ENV:ROOT_URL}$1/latest/$1.%{ENV:SYNTAX} [R=303,L]

RewriteCond %{ENV:SYNTAX} ^html$

RewriteRule ^(.+)$ https://schema.gov.it/lodview/<nome-cartella>/controlled-vocabulary/$1 [R=303,L]

RewriteRule ^(.+)/(.+)/(.+)$ https://schema.gov.it/lodview/<nome-cartella>/controlled-vocabulary/$1/$2/$3 [R=303,L]

Header set Access-Control-Allow-Origin *

Options +FollowSymLinks

RewriteEngine on

SetEnvIf Accept ^.*application/rdf\+xml.* SYNTAX=rdf

SetEnvIf Accept ^.*application/rdf\+xml.* SYNTAX=owl

SetEnvIf Accept ^.*application/n-triples.* SYNTAX=n3

SetEnvIf Accept ^.*text/turtle.* SYNTAX=ttl

SetEnvIf Accept ^.*text/html.* SYNTAX=html

SetEnvIf Request_URI ^.*$ ROOT_URL=<url-git>

RewriteCond %{ENV:SYNTAX} ^(rdf|ttl|owl|n3)$

RewriteRule ^([a-zA-Z-_0-9]+)(/?)$ %{ENV:ROOT_URL}$1/latest/$1.%{ENV:SYNTAX} [R=303,L]

RewriteCond %{ENV:SYNTAX} ^html$

RewriteRule ^(.+)(/.+)$ https://schema.gov.it/lodview/<nome-cartella>/onto/$1$2 [R=303,L]

RewriteCond %{ENV:SYNTAX} ^html$

RewriteRule ^(.+)/$ https://schema.gov.it/lode/extract?url=https://w3id.org/italia/<nome-cartella>/onto/$1 [R=303,L]

RewriteCond %{ENV:SYNTAX} ^html$

RewriteRule ^(.+)$ https://schema.gov.it/lode/extract?url=https://w3id.org/italia/<nome-cartella>/onto/$1 [R=303,L]

Header set Access-Control-Allow-Origin *

Options +FollowSymLinks

RewriteEngine on

SetEnvIf Request_URI ^.*$ ROOT_URL=https://schema.gov.it/lodview/<nome-cartella>/data/

RewriteRule ^(.*)$ %{ENV:ROOT_URL}$1 [R=303,L]

RewriteRule ^(.*)/$ %{ENV:ROOT_URL}$1 [R=303,L]

Esempi di strumenti a supporto dei test¶

Il Contributore è responsabile della scrittura ed eventuale correzione dei file htaccess che vengono pubblicati sul w3id; pertanto, è tenuto a verificarne la correttezza.

A titolo di esempio, un possibile approccio per testare gli htaccess prima della pubblicazione sul w3id potrebbe basarsi sull’installazione di un server Apache, in un container o macchina virtuale, e la configurazione dei file htaccess all’interno di esso. Questo consentirebbe di eseguire test approfonditi sui redirect a partire dal server di test.

Per i test successivi alla pubblicazione su w3id dei file htaccess e dell’harvesting sul Catalogo, un’opzione può essere l’utilizzo di cURL per verificare la correttezza delle regole di redirect. In particolare, in ciascuno dei file htaccess sono definite una o più regole di redirect basate sul contenuto (es. html, rdf, turtle, ecc.). Per testare tutte le regole, occorre innanzitutto individuare URI utili a stressare le regole di redirect contenute in tutti i file htaccess (onto, controlled-vocabulary e data). Successivamente, per ciascuna tipologia di risorsa occorre testare, con l’URI individuato, tutti i possibili contenuti gestiti dal relativo file htaccess, e verificare che il redirect sia quello atteso. In caso contrario, il Contributore dovrà aprire una pull request sul git del w3id al fine di correggere il file htaccess.

La generica riga di comando in input da inserire nel prompt dei comandi è la seguente:

curl [URI] --header “Accept: [Content type]”

Di seguito viene fornito un esempio di utilizzo di cURL per verificare la correttezza dei redirect nel caso di una ontologia.

Prompt dei comandi- cURL per verifica redirect

Nel caso d’esempio, l’URI fornito è il seguente: https://w3id.org/italia/work-accident/onto/core/, mentre il contenuto richiesto è text/html, ovvero uno di quelli gestiti dal relativo file htaccess per le ontologie. Il risultato della cURL mostra come stato http il valore 303_See_Other, che indica che l’indirizzamento avviene con successo, e come indirizzo di atterraggio quello costruito dall’apposita regola di redirect nel file htaccess, come atteso.

Nuovo vocabolario controllato¶

Il vocabolario controllato è un dataset aperto e, pertanto, è metadatato seguendo le linee guida nazionali sui dati aperti, adottando cioè il profilo nazionale di metadatazione DCAT-AP_IT e una licenza aperta.

Nel contesto delle iniziative per promuovere le politiche di valorizzazione del patrimonio informativo pubblico, AGID (Agenzia per l’Italia Digitale) ha collaborato con un Gruppo di Lavoro composto da amministrazioni centrali e locali per definire il profilo nazionale dei metadati (DCAT-AP_IT).

Questo profilo permette la documentazione dei dati di tipo aperto nel Catalogo, in linea con la specifica DCAT-AP (1.1), definita nell’ambito del programma ISA della Commissione Europea.

È reso, dunque, disponibile da parte di AGID un validatore di file aderente al profilo DCAT-AP_IT: può essere utilizzato dal Contributore al fine di verificare il rispetto delle specifiche in oggetto, ricordando che eventuali errori segnalati su dcatapit:Catalog e su owl:versionInfo possono essere ignorati.

Inoltre, è necessario aggiungere al dataset il metadato ndc:keyConcept definito nell’ontologia NDC . Il key concept è il concetto principale o chiave a cui il vocabolario controllato si riferisce. Ad esempio, per il dataset https://w3id.org/italia/controlled-vocabulary/classifications-for-public-services/authentication-type il concetto chiave, quindi il valore della proprietà ndc:keyConcept, è authentication-type (il tipo di autenticazione). Questo metadato è necessario per abilitare i meccanismi di harvesting del Catalogo.

Essendo un vocabolario controllato un dataset per organizzare la conoscenza, esso è rappresentato utilizzando lo standard web di riferimento per i sistemi di organizzazione della conoscenza, ossia l’ontologia SKOS.

In particolare, il Contributore:

• definisce il ConceptScheme di SKOS che rappresenta tutto il vocabolario controllato collegandolo ai singoli concetti di primo livello mediante la proprietà skos:hasTopConcept. Un vocabolario controllato può essere infatti una lista di codici (code list), una tassonomia (taxonomy), oppure qualcosa di più complesso come un tesauro. La proprietà skos:hasTopConcept collega tutti i singoli concetti in una lista di codici, i concetti di primo livello negli altri casi più articolati;

• per ciascun concetto, inoltre, specifica le seguenti proprietà:

  • skos:notation con l’identificativo univoco associato al concetto;
  • skos:prefLabel con l’etichetta principale di riferimento per il concetto definita con almeno il tag in italiano. È opportuno aggiungere anche la lingua inglese, soprattutto se il vocabolario è utilizzato in un contesto di interoperabilità anche transfrontaliera. Si ricorda che l’etichetta che rappresenta il valore di questa proprietà deve essere esplicita e non contenere abbreviazioni di testo che la renderebbe comprensibile solo da parte dell’ente che propone il vocabolario. È opportuno che l’etichetta principale sia nella forma singolare, lasciando eventualmente le forme plurali in un’etichetta alternativa rappresentata con la proprietà skos:altLabel;
  • skos:inScheme che assume come valore l’URI del vocabolario controllato che si sta definendo.

• in presenza di tassonomie o tesauri indica anche i concetti di livello inferiore e superiore attraverso le proprietà skos:narrower e skos:broader nonché di quanti livelli si compone il vocabolario mediante la proprietà skos:numberOfLevels, il cui valore indica il numero di livelli gerarchici previsti dal vocabolario controllato.

È opportuno che altre proprietà SKOS siano aggiunte ai vari concetti, come per esempio skos:definition quando una definizione formale del concetto è nota , skos:note per aggiungere qualsiasi altra nota, qualora esistente.

Qualora un concetto sia allineato semanticamente in maniera più o meno forte ad analoghi concetti definiti in altri vocabolari controllati esistenti nel web (es. schema.org, EU authority list) è buona norma utilizzare le proprietà skos:exactMatch (i due concetti sono di fatto la stessa cosa), skos:relatedMatch (i due concetti sono tra loro relazionati, nel senso più generale), skos:closeMatch (i due concetti sono molto simili ma non esattamente la stessa cosa) al fine di creare collegamenti tra diversi dataset dei vocabolari controllati (linked open data).

Nuova ontologia¶

Nel caso di proposta di una nuova ontologia, il Contributore rispetta le seguenti indicazioni:

• consegnare un’ontologia che non presenta errori sintattici. Non saranno valutate ontologie che non riescono a essere aperte con successo da software di editing di ontologie come per esempio Protégé;
• l’ontologia è almeno serializzata in RDF/Turtle (serializzazione utilizzata nella procedura di harvesting di schema.gov.it);
• l’ontologia è metadatata attraverso l’ontologia ADMS-AP_IT. Questo profilo di metadatazione è specifico per ontologie e si basa su DCAT-AP_IT. È questa metadatazione che consente di abilitare l’harvesting dell’ontologia in schema.gov.it. Per verificare la correttezza della metadatazione, i Contributori avranno a disposizione un modulo di pre-harvesting raggiungibile da un’apposita pagina web, così come espresso nel workflow in Attività propedeutiche alla contribuzione al Catalogo;
• si verifica con dei ragionatori automatici, presenti come plug-in nei principali editor di sviluppo di ontologie come ad esempio Protégé o Eddy, che l’ontologia prodotta non abbia inconsistenze semantiche e che quello che si vuole modellare sia correttamente inferito dal ragionatore;
• le classi e proprietà di ogni tipo delle ontologie sono sempre annotate con almeno le proprietà rdfs:label e rdfs:comment in italiano. Qualora l’ontologia abbia una potenzialità in un contesto transfrontaliero, si fornisce anche la versione in lingua inglese delle stesse proprietà. È opportuno inoltre specificare la proprietà di annotazione rdfs:isDefinedBy con l’URI dell’ontologia;
• riutilizzare direttamente tutte le ontologie già esistenti in schema.gov.it qualora questo si applichi alla nuova modellazione. Questo consente anche di riutilizzare pattern di modellazione già implementati che, da letteratura scientifica, hanno dimostrato di fornire maggiori garanzie di interoperabilità semantica tra modellazioni diverse. A titolo d’esempio: se si deve definire un concetto di persona fisica oppure di organizzazione (pubblica o privata che sia) ma anche concetti legati al tempo o a ruoli di agenti che agiscono su oggetti del dominio è necessario riutilizzare rispettivamente le ontologie CPV (Persone), COV (Organizzazioni), TI (tempo), RO (ruoli);
• si ricorda che il riutilizzo diretto di concetti e/o proprietà già esistenti comporta l’ereditarietà di tutti i vincoli di cardinalità (restrizioni OWL) già definiti nelle ontologie di schema.gov.it;
• qualora ci sia necessità di aggiungere altre proprietà o vincoli di cardinalità a concetti già esistenti in ontologie già disponibili, o si richiede tale aggiunta agli Amministratori del Catalogo per agire direttamente nelle ontologie di schema, oppure si definisce un proprio concetto che potrà diventare sottoclasse del concetto già esistente in ontologie esistenti di schema.gov.it;
• è raccomandato allineare la nuova ontologia all’ontologia di livello top nazionale l0. Questa raccomandazione ha alcuni vantaggi: 1) aiuta a comprendere meglio cosa si sta modellando. Se si modella un’entità che è concetto questa non può essere anche un evento; 2) l’ontologia l0 aiuta a collegare tutte le ontologie tra loro creando quindi una grossa rete di ontologie nazionali. Il collegamento tra modelli concettuali abilita il collegamento tra i dati rappresentati con quei modelli; 3) l0 è molto utile per verificare, attraverso l’inferenza semantica, eventuali inconsistenze semantiche in un’ottica più generale di rete più che di singola ontologia;
• è possibile aggiungere vincoli di cardinalità mediante restrizioni OWL, ma è bene non vincolare troppo le varie definizioni per dare più possibilità di riutilizzo alle ontologie anche in altri potenziali contesti, visto la valenza nazionale che nuove ontologie possono assumere con la pubblicazione in schema.gov.it. A tal proposito si suggerisce di definire restrizioni OWL come sottoclassi della classe a cui si riferiscono così da specificare una condizione necessaria ma non sufficiente e valutare attentamente se il vincolo di cardinalità è di fatto sempre stringente (costrutti come some, exactly 1) o meno (max 1, ecc.). Qualora ci siano vincoli di cardinalità più stringenti dal punto di vista applicativo, è bene che il Contributore consideri la possibilità di rilassare alcune restrizioni OWL definite nell’ontologia e creare a parte un vero e proprio profilo applicativo mediante regole SHACL, standard web pubblicato dal W3C. Questa pratica, tra l’altro, è quella adottata da alcuni paesi europei (es. Belgio) e dalla Commissione Europea stessa nel contesto di iniziative di interoperabilità semantica quali i core vocabulary, l’ontologia ePO sul’e-procurement, l’ontologia ELM – European Learning Model;
• è opportuno modularizzare il più possibile le ontologie, più che creare ontologie che contengono la rappresentazione di svariati domini/tipologie di dati. L’evidente vantaggio della modularizzazione è quello di riuscire a gestire in modo più agevole eventuali evoluzioni future che potrebbero anche seguire diverse frequenze di aggiornamento delle diverse tipologie di dato;
• è opportuno utilizzare ontology design pattern e un approccio agile alla modellazione con rilasci più frequenti e definizioni di versioni anche instabili dell’ontologia pian piano raffinate con requisiti nuovi fino alla versione finale. Gli ontology design pattern sono soluzioni di modellazione già disponibili, riusabili ed efficaci che possono essere specializzati o direttamente applicati nel dominio da modellare e che risolvono problemi di modellazione ricorrenti (es. un qualcosa che cambia nel tempo). Essi aiutano a ridurre l’arbitrarietà nel design dell’ontologia e consentono di ridurre gli errori di modellazione e quindi migliorare la qualità delle ontologie. Si ricorda, come prima menzionato, che già le ontologie esistenti implementano ontology design pattern che si devono riutilizzare (es. ruoli nel tempo, oggetti che variano nel tempo, valori, ecc.);
• è buona norma allineare l’ontologia anche ad altre ontologie esistenti nel Web dei Dati, qualora questo sia applicabile;
• è possibile corredare l’ontologia di una rappresentazione grafica dei concetti e delle loro relazioni. A tale scopo i Contributori sono liberi di utilizzare strumenti di loro preferenza. Solo a titolo d’esempio si possono citare diagrammi di rappresentazione grafica che utilizzano la notazione UML, che possono essere prodotti con strumenti quali diagrams.net, Visual Paradigm, StarUML oppure che usano notazioni tecniche specifiche di disegno ontologico come per esempio Graffoo (che è possibile abilitare con strumenti come yEd oppure draw.io) o Graphol (che è possibile utilizzare attraverso strumenti come Eddy).

Nuovi schemi dati¶

I nuovi schemi dati devono utilizzare le risorse semantiche, come ontologie e vocabolari controllati, qualora siano catalogati in schema.gov.it e siano pertinenti rispetto ai dati descritti dagli schemi.

Da un lato le risorse semantiche sono un valido aiuto per la modellazione degli schemi: è infatti possibile creare una descrizione dei dati secondo uno dei formati del paradigma linked-data (ad esempio JSON-LD ), quindi ricavare lo schema sintetizzando e semplificando. Si andranno quindi a includere soltanto le componenti variabili e i loro identificativi abbreviati, eliminando il più possibile le parti ridondanti e gli annidamenti. In particolare, per i vocabolari controllati saranno oggetto di trasferimento soltanto le componenti variabili delle URI.

Se invece si parte da uno schema dati già definito, è importante indicare come poter convertire in modo non ambiguo i dati trasferiti dal loro formato al formato del paradigma linked-data.

Siccome le specifiche OpenAPI prevedono che il formato di scambio dati sia JSON, il formato del paradigma linked-data più compatibile è JSON-LD, che aggiunge la possibilità di inserire alcune specifiche per la descrizione semantica, in particolare:

• il @context che permette di definire sia le abbreviazioni comuni, che i concetti semantici a cui associare ciascun attributo
• il @type che permette di associare a ciascun oggetto il proprio oggetto semantico corrispondente

Inoltre, è possibile definire gli attributi di tipo @id che fanno riferimento concetti esterni, che possono essere altri oggetti o elementi di un vocabolario controllato.

Gli schemi dati per essere sottoposti al processo di harvesting debbono contenere due file: il file di metadati in formato RDF/Turtle, e il modello dello schema dati in formato OpenAPI.

In particolare, il file di metadati deve avere l’estensione .ttl e un nome specifico, ossia index.ttl.

Il file index.ttl, come per le ontologie, deve contenere tutti i metadati previsti dall’ontologia ADMS-AP_IT. Questo profilo di metadatazione si basa su DCAT-AP_IT. È l’adozione di questo modello che consente l’harvesting anche degli schemi dati.

Mentre il file che riporta lo schema del servizio deve avere l’estensione .yaml (se viene utilizzata la versione 3.0 di OpenAPI si usa oas3.yaml).

Il file OpenAPI deve essere compatibile con il nuovo modello d’Interoperabilità (ModI).

Per descrivere le connessioni fra gli schemi dati e il loro equivalente nel paradigma linked-data, si utilizzano alcuni attributi custom, che vengono derivati dal formato JSON-LD:

• x-jsonld-type permette di indicare il tipo di oggetto che si sta descrivendo
• x-jsonld-context permette di definire il @context di JSON-LD. Notare che è possibile definire @context annidati, via via che si esprimono i concetti

In particolare, le sezioni principali e obbligatorie all’interno del file che riporta lo schema del servizio sono le seguenti:

• info: le informazioni iniziali riguardanti il titolo (title) e la descrizione (description) dello schema dati del servizio;

• components:

  • schemas: vengono descritti i concetti all’interno del servizio, definendo quali sono i concetti di input obbligatori (required). Per ogni concetto sono dichiarate le seguenti voci:

  • type: il tipo di dato (object, string, integer);

  • description: si riporta la URI del concetto di riferimento;

  • per i concetti di tipo object è necessario elencare le properties. Per le properties è necessario definire il tipo di dato (type): se si tratta di un object si riporta il riferimento al concetto, altrimenti è necessario riportare il tipo di format e quando richiesto il pattern;

  • x-jsonld-type: si riporta la URI del concetto di riferimento;

  • x-jsonld-context:

    • @vocab: si riporta la radice della URI dell’ontologia maggiormente referenziata all’interno dello schema dati del servizio.

Si riporta un breve esempio di seguito:

components:
  schemas:
    TaxCode:
      type: string
      description: https://w3id.org/italia/onto/CPV/taxCode.
      example: RSSMRA75L01H501A
      maxLength: 16
      minLength: 11
    Person:
      type: object
      description: https://w3id.org/italia/onto/CPV/Person
      x-jsonld-type: https://w3id.org/italia/onto/CPV/Person
      x-jsonld-context:
        "@vocab": https://w3id.org/italia/onto/CPV/
       tax_code:
         "@id": taxCode
       date_of_birth: dateOfBirth
       family_name: familyName
       given_name: givenName
      properties:
        tax_code:
          $ref: "#/components/schemas/TaxCode"
        date_of_birth:
          format: date
          type: string
         pattern: ([0-9]{4})-([0-1][0-9])-([0-3][0-9])
        family_name:
          type: string
        given_name:
          type: string

Modifiche a vocabolari controllati esistenti¶

Qualora si propongano modifiche a vocabolari esistenti è necessario specificare nella proposta quanto segue:

• se un concetto già esistente è da considerarsi deprecato. Nel qual caso si dovrà aggiungere al concetto la proprietà owl:deprecated per indicare che non è più valido;
• aggiungere la definizione del/dei nuovo/nuovi concetto/i seguendo esattamente le definizioni dei concetti già esistenti nel vocabolario (anche in termini di URI);
• qualora si voglia aggiungere un nuovo livello a una tassonomia o a un tesauro, è necessario motivare la richiesta e predisporre il nuovo livello considerando l’aggiunta delle proprietà skos:narrower e skos:broader prima menzionate ove applicabili nei livelli precedenti già presenti nel vocabolario controllato.

Modifiche a ontologie esistenti¶

Le modifiche vengono esplicitate evidenziando i requisiti (domande di competenza) che portano a richiedere la modifica di concetti e/o proprietà già esistenti o cambiamenti nelle restrizioni OWL attualmente inserite nelle ontologie esistenti. Le domande di competenza sono di fatto interrogazioni sui dati che la modellazione deve poter supportare.

Nuovi concetti e/o proprietà rispetto a quelle esistenti, sempre motivate da specifici requisiti da evidenziare, dovranno essere definiti seguendo esattamente le definizioni già fornite nell’ambito delle ontologie esistenti (i.e., specificando tutte le annotazioni che già vengono utilizzate sia in lingua italiana che in lingua inglese, specificando eventuali restrizioni OWL se necessarie).

Si raccomanda di non effettuare cambiamenti negli URI per concetti e/o proprietà già definite, per via della loro natura di identificativi univoci e soprattutto persistenti nel tempo, eccetto il caso in cui i cambiamenti siano indispensabili per garantire un funzionamento complessivo dell’asset (anche in termini di coerenza semantica) e del Catalogo, o quando gli URI contengono evidenti errori di battitura che ne possano compromettere l’usabilità e la leggibilità.

Modifiche a schemi dati¶

Le modifiche da proporre a schemi dati saranno valutate nel caso in cui saranno evidenziati nuovi casi d’uso. Sulla base di queste nuove necessità si decide se modificare uno schema dati già esistente o crearne uno nuovo. Le modifiche proposte per gli schemi dati dovranno seguire tutte le regole sintattiche e semantiche definite nel contesto del Catalogo.

Struttura di base del repository¶

La struttura di base del repository deve rispettare il seguente template:

• Ontologie: in assets/ontologies;
• Vocabolari controllati: in assets/controlled-vocabularies;
• Schemi: in assets/schemas.

Contenuto del repository¶

I file devono essere codificati in UTF-8.

Le risorse semantiche devono essere presenti almeno nel seguente formato:

• Ontologie: RDF/Turtle (media-type text/turtle) con estensione del file .ttl;
• Vocabolari controllati: RDF/Turtle (media-type text/turtle) con estensione del file .ttl;
• Schemi dati: OAS3 (.oas3.yaml) e turtle dei metadati (file index.ttl).

Possono essere presenti ulteriori serializzazioni (es. RDF/XML, JSON-LD, CSV, …) che verranno ignorate dal processo di harvesting del Catalogo.

Possono essere presenti eventuali file di documentazione, ma solo in formato Markdown (.md).

Nomi delle cartelle e dei file¶

I nomi di file e directory devono rispettare il seguente pattern \`[A-Za-z0-9\_-.]{,64}.

Il nome di ciascun file deve corrispondere al nome della relativa risorsa nell’URI utilizzato per referenziarla.

I nomi dei file di una directory devono corrispondere al nome della directory che li contiene, a meno dell’estensione degli stessi.

Il controllo può essere disattivato nel caso in cui il Contributore abbia implementato una propria soluzione per le URI stabili, oppure se ha configurato una soluzione basata sul W3id (Identificativi univoci delle risorse) che tratti opportunamente eventuali discrepanze tra nomi dei file, nomi delle cartelle che li contengono e nomi delle risorse nelle relative URI.

Proiezioni in CSV dei vocabolari controllati¶

Le directory del vocabolario controllato possono contenere una proiezione in formato csv del vocabolario insieme ai metadati necessari per mappare i campi del csv alle risorse presenti nel file rdf.

Nel caso in cui si voglia pubblicare anche la proiezione csv per un vocabolario controllato, questo deve avere la struttura di file piatto, ossia riportare tutte le voci delle classificazioni dal primo livello al livello di foglia. Occorre rispettare le seguenti regole:

• generare la proiezione possibilmente mediante strumenti come JSON-LD framing;

• eventuali commenti nel csv devono iniziare col carattere #;

• l’header del csv ovvero la prima riga contenente i nomi delle colonne, deve rispettare le seguenti regole sulla base della presenza o meno, nella stessa directory del csv, del file di metadati in un frictionless data package, annotato secondo le specifiche indicate in REST API Linked Data Keywords:

  • se presente, allora i nomi delle colonne devono essere conformi a quanto indicato nei metadati.
  • se non presente, i nomi delle colonne devono solo rispettare il seguente pattern: ^[a-zA-Z0-9_]{2,64}$.

• si suggerisce di creare la riga di header di vocabolari controllati alberati introducendo tante colonne quanti sono i livelli secondo la nomenclatura: codice_1_livello, label_ITA_1_livello, label_ENG_1_livello, definizione, … codice_n_livello, label_ITA_n_livello, label_ENG_n_livello, definizione, NOTE (Dove n rappresenta il numero di livelli della classificazione);

• le righe successive del csv devono contenere i valori delle colonne separati da , (virgola) e, se valori relativi a campi di tipo stringa, racchiusi in " (doppie virgolette).

I metadati di cui al precedente elenco devono essere espressi tramite un file datapackage con estensione .json, .yaml o .yml.

Nel caso in cui le voci di un vocabolario siano già presenti in un repository triple store è possibile estrarne il contenuto con una query SPARQL secondo il seguente formato:

SELECT DISTINCT ?codice_1_livello ?label_1_livello_it ?label_1_livello_en ?label_1_livello_fr ?label_1_livello_de

WHERE{

<https://w3id.org/italia/controlled-vocabulary/territorial-classifications/countries/italy/ITA> a skos:Concept;

skos:notation ?codice_1_livello;

skos:prefLabel ?label_1_livello_it;

skos:prefLabel ?label_1_livello_en;

skos:prefLabel ?label_1_livello_fr;

skos:prefLabel ?label_1_livello_de.

FILTER (LANG(?label_1_livello_it) = 'it')

FILTER (LANG(?label_1_livello_en) = 'en')

FILTER (LANG(?label_1_livello_fr) = 'fr')

FILTER (LANG(?label_1_livello_de) = 'de')

}

Versionamento¶

Le directory degli asset possono avere sub-directory per supportare il versionamento. Il nome delle sub-directory rispetta il pattern: (latest|v?[0-9]+(\.[0-9]+){0,2}).

Una directory contenente asset non contiene contemporaneamente sub-directory versionate con e senza il prefisso v perché questo rende impossibile ordinare le versioni.

In Istruzioni su come predisporre il repository sono contenuti alcuni esempi di versionamento delle risorse semantiche.

Approfondimenti sugli schemi dati¶

Gli schemi utilizzano delle directory versionate come descritto nel corso del documento.

Gli schemi per le API vengono pubblicati in formato OpenAPI, corrispondenti ad una estensione di JSON Schema Draft 4, incorporato nella sezione #/components/schema del file OAS compatibilmente con le Linee Guida per l’interoperabilità tecnica. L’estensione del file è .oas3.yaml.

È opportuno che il file YAML contenga i riferimenti semantici descritti nel documento I-D-polli-restapi-ld-keywords attraverso:

• il campo custom x-jsonld-context contenente un @context JSON-LD conforme alle indicazioni contenute in JSON-LD 1.1;
• il campo custom x-jsonld-type contenente il riferimento ad un rdf:type.

I metadati associati sono pubblicati solo in formato RDF/Turtle (media type text/turtle) in un apposito file index.ttl, uno per ciascuno schema dati. È opportuno che questo file sia generato automaticamente dal documento OpenAPI.

È possibile verificare sintatticamente gli schemi forniti utilizzando l’OpenAPI Checker.

Esempi¶

bash
┌─ README.md
├─ publiccode.yaml
|
├─ assets/ontologies/
│ ├─ Onto1/
│ │ ├─ onto1.ttl
│ │ └─ onto1.rdf
│ ├─ Onto2/
│ │ └─ README.md
│ ├─ Onto3/
│ │ ├─ Other/
│ │ │ └─ temp.md
│ │ └─ onto3.ttl
│ ├─ Onto4/
│ │ └─ latest/
│ │   ├─ onto1.ttl
│ │   └─ onto1.rdf
│ └─ notes.md
|
└─ assets/controlled-vocabularies/
  └─ ...

bash
└── assets
  ├── ontologies
  │  └── Car
  │  |  ├── 1.3
  │  |  ├── 202101
  │  |  └── 4.5.6
  │  └── Person
  │    ├── v1.3
  │    └── v4.5.6
  └── schemas
    └── Person
      └── latest

bash
└── assets
  ├── ontologies
  │  └── MyOntology
  │    ├── v1.4-beta
  │    ├── versione 2.9
  │    ├── v4..6
  │    ├── v.3
  │    └── 4.5.

bash
assets/
 ontologies/
  MyOntology/
   CHANGELOG.md
   README.md
   v1.2/
    MyOntology.ttl
    MyOntology.rdf
   v1.1/
    MyOntology.ttl
   latest/
    MyOntology.ttl
    MyOntology.rdf
    LATEST.md

bash
assets/
 controlled-vocabulary/
  my-codelist/
   CHANGELOG.md
   README.md
   my-codelist.ttl
   my-codelist.csv
   datapackage.yaml
   framing.yamlld

turtle

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

@prefix at: <http://publications.europa.eu/ontology/authority/> .

@prefix atold: <http://publications.europa.eu/resource/authority/> .

@prefix dc: <http://purl.org/dc/elements/1.1/> .

@prefix owl: <http://www.w3.org/2002/07/owl#> .

@prefix c: <http://publications.europa.eu/resource/authority/country/> .

c:ITA a skos:Concept;

 dc:identifier "ITA";

 skos:prefLabel "Italy"@en, "Italia"@it, "Italie"@fr;

 skos:inScheme atold:country

.

c:DEU a skos:Concept;

 dc:identifier "DEU";

 skos:prefLabel "Germany"@en, "Germania"@it, "Allemagne"@fr;

 skos:inScheme atold:country

.

c:ESP a skos:Concept;

 dc:identifier "ESP";

 skos:prefLabel "Spain"@en, "Spagna"@it, "Espagne"@fr;

 skos:inScheme atold:country

.

csv

# It is possible to add comments

#  metadata is into datapackage.yaml

"id","label_en","label_it","label_fr"

"ITA","Italy","Italia","Italie"

"DEU","Germany","Germania","Allemagne"

"ESP","Spain","Spagna","Espagne"

yaml

# Datapackage.yaml

profile: data-package

resources:

 - name: my-codelist

  path: my-codelist.csv

  profile: tabular-data-resource

  dialect:

   delimiter: ","

   doubleQuote: true

   lineTerminator: ""

  schema:

   x-jsonld-type: skos:Concept

   x-jsonld-context:

    "@context":

     skos: http://www.w3.org/2004/02/skos/core#

     dc: http://purl.org/dc/elements/1.1/

     at: http://publications.europa.eu/ontology/authority/

     atold: http://publications.europa.eu/resource/authority/

     c: http://publications.europa.eu/resource/authority/country/

     id: dc:identifier

     label_it:

      "@id": skos:prefLabel

      "@language": it

     label_en:

      "@id": skos:prefLabel

      "@language": en

     label_fr:

      "@id": skos:prefLabel

      "@language": fr

   fields:

    - name: id

     type: string

    - name: label_en

     type: string

    - name: label_it

     type: string

    - name: label_fr

     type: string

yaml

openapi: 3.0.1

...

components:

 schemas:

  Person:

   type: object

   x-jsonld-type: "https://w3id.org/italia/onto/CPV/Person"

   x-jsonld-context:

    "@vocab": "https://w3id.org/italia/onto/CPV/"

    nome_proprio: givenName

    cognome: familyName

   properties:

    nome_proprio: {type: string, ..}

    cognome: {type: string, ..}

   ...

bash
assets/
 schemas/
  Person/
   CHANGELOG.md
   README.md
   person.oas3.yaml
   index.ttl

xml

<TABLE VL="IT" NAME="countries">

 <LIBELLE CODE="1A0">Kosovo</LIBELLE>

 <LIBELLE CODE="ABW">Aruba</LIBELLE>

 <LIBELLE CODE="AFG">Afghanistan</LIBELLE>

...

</TABLE>

xml

<?xml version="1.0" encoding="UTF-8"?>

<gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">

  <Identification>

   <CanonicalUri>http://publications.europa.eu/resource/dataset/country</CanonicalUri>

<CanonicalVersionUri>http://publications.europa.eu/resource/dataset/country/20210616-0</CanonicalVersionUri>

<LocationUri>http://publications.europa.eu/resource/distribution/country/20210616-0/xml/gc/Country.gc</LocationUri>

  </Identification>

  <ColumnSet>

   <Column Id="code" Use="required">

     <ShortName>Code</ShortName>

     <Data Type="normalizedString" Lang="eng"/>

   </Column>

   <Column Id="Name" Use="optional">

     <ShortName>Name</ShortName>

     <Data Type="string" Lang="eng"/>

   </Column>

   <Column Use="optional" Id="ita_label">

     <ShortName>engLabel</ShortName>

     <Data Type="string" Lang="ita"/>

   </Column>

  ...

  </ColumnSet>

  <SimpleCodeList>

   <Row>

     <Value ColumnRef="code">

      <SimpleValue>ITA</SimpleValue>

     </Value>

     <Value ColumnRef="Name">

      <SimpleValue>Italy</SimpleValue>

     </Value>

     <Value ColumnRef="ita_label">

      <SimpleValue>Italy</SimpleValue>

     </Value>

  ...

  <SimpleCodeList>