Lo Schema Editor offre funzionalità per incorporare le informazioni di metadatazione semantica nel OpenAPI/JSON Schema dell’API. Due funzioni fondamentali sono la possibilità di configurare l’endpoint SPARQL, utile poi per l’interrogazione di risorse di tipo RDF, e l’attivazione del completamento automatico per termini e classi.

Configurare l’endpoint SPARQL

Lo Schema Editor interroga risorse esterne utilizzando SPARQL, un linguaggio pensato per interrogare dataset RDF.
Di default, l’editor utilizza un endpoint SPARQL preconfigurato. Tuttavia, è possibile modificarlo per collegarsi a un diverso server SPARQL, utile ad esempio quando si lavora con dataset personalizzato o infrastrutture RDF distribuite. Per farlo, cliccare sull’icona hamburger (≡) situata nell’angolo superiore sinistro dell’interfaccia.

Per modificare l’endpoint SPARQL:

• Clicca sull’icona hamburger (≡) nell’angolo in alto a sinistra dell’interfaccia.
• Seleziona la voce Configurazione dal menu laterale.
• Inserisci l’URL del nuovo endpoint SPARQL nel campo dedicato. Una volta salvata la configurazione, l’editor utilizzerà il nuovo endpoint per tutte le interrogazioni.

Immagine descrittiva di finalizzazione della configurazione dell’endpoint SparQL.

Utilizzare il completamento automatico

Schema editor è in grado di suggerire automaticamente termini e classi durante la digitazione, basandosi su un insieme selezionato di vocabolari disponibili sul catalogo schema.gov.it. Per utilizzare l’autocompletamento:

• Premendo la combinazione CTRL + SPACE si aprirà un menu a tendina con un elenco di suggerimenti compatibili;
• Digitando del testo l’elenco verrà filtrato dinamicamente;
• Premendo INVIO su un suggerimento, l’editor completerà automaticamente il campo con l’URI corretto della classe o proprietà selezionata.

Questa funzionalità semplifica notevolmente l’inserimento di riferimenti corretti e riduce il rischio di errori di sintassi o URI non validi.

Immagine descrittiva di funzionamento dell’autocompletamento.

La sezione Data Models dello Schema Editor offre una panoramica strutturata di tutte le classi RDF definite nello schema. È pensata per facilitare l’analisi delle proprietà associate a ciascuna classe e dei relativi collegamenti semantici.

Funzionalità principali

1. Visualizzazione automatica delle classi RDF L’editor recupera automaticamente tutte le classi RDF presenti nello schema. Per ciascuna classe, vengono elencate:
   • Le proprietà associate;
   • I collegamenti semantici risultanti dalle mappature con le classi di riferimento.
2. Dettagli per ogni proprietà Ogni proprietà visualizzata è arricchita da informazioni utili per la comprensione del modello:
   • Tipo sintattico (es. stringa, numero, oggetto);
   • Tipo semantico (URI RDF associato);
   • Descrizione testuale;
   • Esempio di utilizzo, generato in base alle definizioni dello schema.
3. Calcolo dell’OntoScore – Indicatore di copertura semantica Lo Schema Editor calcola un indicatore chiamato OntoScore, che misura il livello di mappatura semantica dello schema. È definito come il rapporto tra il numero totale di proprietà presenti nello JSON Schema e il numero di proprietà correttamente mappate con una rdf:Property. Questo punteggio aiuta a valutare quanto lo schema sia allineato semanticamente con vocabolari RDF.
4. Accesso ai vocabolari controllati Quando una classe è collegata a un vocabolario controllato, compare il pulsante "Show values". Cliccandolo, si accede direttamente alla sezione corrispondente su schema.gov.it, dove sono elencati tutti i valori ammessi per quella proprietà.

Immagine descrittiva della sezione Data Models con le sue funzionalità.

Navigazione degli strumenti per l’analisi

Questa sezione dello Schema Editor raccoglie un insieme di strumenti pensati per l’analisi semantica, la visualizzazione RDF e la validazione della compatibilità con JSON-LD. Attraverso diversi pannelli interattivi, è possibile esplorare la struttura dello schema, comprenderne il significato semantico e verificarne il comportamento in contesti RDF reali.

Utilizzare JSON-LD Playground

Lo Schema Editor permette di generare automaticamente un esempio e aprirlo nello strumento esterno JSON-LD Playground. Questa funzione consente di:

• Visualizzare il JSON di input prodotto dallo schema;
• Esaminare il contesto JSON-LD e il relativo @type;
• Ottenere una serializzazione RDF nei formati Turtle, RDF/XML e N-Quads.

Questo strumento è utile per testare la correttezza della rappresentazione semantica dei dati.

Immagine descrittiva di analisi semantica con JSON-LD Playground.

Utilizzare le triplette RDF

La sezione RDF mostra le informazioni dello schema in triplette RDF (nella forma soggetto – predicato – oggetto), fornendo una rappresentazione chiara della struttura semantica. Questa vista permette di:

• Esplorare visivamente le relazioni semantiche tra entità e proprietà;
• Verificare la coerenza del modello rispetto al grafo RDF;
• Comprendere come le istanze dello schema verranno interpretate nei sistemi semantici

Immagine descrittiva di triplette RDF.

Utilizzare JSON-LD Context

Il contenuto della sezione JSON-LD Context viene generato automaticamente a partire dai metadati (x-jsonld-type e x-jsonld-context) presenti nello schema. Tra le principali caratteristiche:

• Rispetta la gerarchia dello schema, mantenendo un contesto coerente;
• Applica l’ereditarietà automatica del contesto ai livelli figli, se non diversamente specificato;
• Genera un output conforme alle specifiche JSON-LD, pronto per essere integrato in sistemi basati su ontologie RDF.

Questo pannello è fondamentale per garantire un’integrazione semantica efficace e una pubblicazione dati interoperabile.

Immagine descrittiva della sezione JSON-LD Context.

L’Action Menu dello Schema Editor offre un accesso rapido a diverse funzionalità utili per gestire, esportare e condividere gli schemi semantici.
È accessibile tramite un apposito pulsante posizionato nell’interfaccia principale dell’editor.

Funzionalità principali

1. Creazione di un nuovo template È possibile generare un template di base, contenente una singola classe di esempio: Person, con le proprietà givenName e familyName. Questo modello base può essere utilizzato per:
   • Esplorare la struttura e le logiche dello schema;
   • Aggiungere facilmente nuove classi e proprietà;
   • Iniziare la definizione di uno schema personalizzato, ad esempio un modello semantico di “Persona” con relative classi ontologiche.
2. Download dello schema Lo schema attualmente in uso può essere scaricato in diversi formati:
   • Formato nativo (“as-is”), utile per il riutilizzo diretto nello Schema Editor;
   • Formato JSON, adatto per l’integrazione in sistemi esterni o per ulteriori elaborazioni.
3. Condivisione dello schema
   È disponibile un’opzione per copiare lo schema come URL, permettendo una condivisione semplice e veloce con altri utenti o strumenti. Questo link mostra una rappresentazione persistente dello schema, pronta per essere aperta nello stesso editor o in ambienti compatibili.
4. Apertura dello schema in un'istanza remota
   Lo stesso schema può essere aperto all’interno di una istanza remota dello Schema Editor, precedentemente configurata (ad esempio, in un’applicazione terza o in un ambiente personalizzato). Questa funzione è particolarmente utile nei contesti in cui l’editor è integrato in un sistema gestionale, un portale documentale, o un ambiente di sviluppo semantico dedicato.

Immagine descrittiva dell’Action menu.

L’RDF Ontological Class Helper è uno strumento integrato nello Schema Editor pensato per supportare gli utenti nella progettazione semantica avanzata degli schemi.

Questa funzionalità aiuta a esplorare le proprietà RDF associate a una specifica classe semantica, facilitando la corretta mappatura delle proprietà e migliorando la qualità semantica complessiva dello schema.

1. Lo strumento esegue automaticamente una query SPARQL sulla classe semantica indicata nel campo x-jsonld-type dello schema.
2. Vengono recuperate tutte le rdf:Property associate alla classe, con dettagli utili per ciascuna proprietà, tra cui:
   • rdfs:range: indica il tipo di valore atteso (es. Literal, URI, ecc.);
   • rdfs:comment: fornisce una descrizione testuale della proprietà;
   • Esempio di utilizzo: aiuta a capire come integrare correttamente la proprietà nello schema.

Le proprietà individuate sono inserite in un pannello interattivo, da cui l’utente può analizzarle e decidere se integrarle o meno nel proprio modello.
Questo strumento è particolarmente utile per estendere la copertura semantica dello schema, garantire un allineamento corretto con vocabolari standard RDF, riutilizzare proprietà esistenti, riducendo la ridondanza e favorendo l’interoperabilità semantica.

Immagine descrittiva dell’utilizzo di RDF Helper