Questa pagina presenta lo strumento di Validation of Repository del Catalogo Nazionale dei Dati Semantici (NDC), gestito congiuntamente dal Dipartimento per la trasformazione digitale e da ISTAT.

Lo strumento esegue una verifica completa di un repository GitHub prima della pubblicazione su NDC, riproducendo on-demand gli stessi controlli che il catalogo applica automaticamente durante l’harvesting.

Consente quindi ai maintainer di una Pubblica Amministrazione di sapere in anticipo se il proprio repository — e gli asset semantici che contiene — è pronto per essere ingerito correttamente nel catalogo nazionale.

L’operazione non ha alcun effetto collaterale: non scrive nulla sul triple store, sull’indice di ricerca o sul database del catalogo.

È un controllo a sola lettura, ripetibile quante volte si desidera.

Lo strumento permette di agevolare il processo di pubblicazione delle risorse semantiche nel catalogo, eseguendo in un’unica passata tre famiglie di controlli su tutti gli asset (.ttl) presenti nel repository:

1. Validazione sintattica RDF — verifica che ogni file Turtle sia sintatticamente valido secondo lo standard RDF 1.1 Turtle.
2. Verifica dei metadati obbligatori — verifica la presenza dei metadati minimi previsti da DCAT-AP_IT e dalle policy NDC (es. licenza, adms:status).
3. Verifica della conformità del repository — verifica che la struttura del repository aderisca al template ufficiale dati-semantic-cookiecutter di Team Digitale (directory standard, workflow CI, hook di pre-commit).

Gli esiti di tutte le verifiche vengono aggregati in un report unificato e classificati secondo una tassonomia comune a tre livelli (Bloccante, Warning, Migliorativo), così da offrire una vista omogenea e facilmente interpretabile.

1. Inserimento dati

Compilare il modulo iniziale indicando il repository GitHub da analizzare.

Premere quindi «Avvia validazione». Il pulsante «Riprova» consente di rilanciare la validazione (ad esempio dopo aver corretto il repository o per cambiare i parametri).

Il repository deve essere pubblico su GitHub. L'URL viene costruito automaticamente come:

https://github.com/{owner}/{repository}

2. Validation status

La validazione è un'operazione asincrona: a seconda della dimensione del repository può richiedere da alcuni secondi a qualche minuto (clonazione, scoperta degli asset, validazione di ogni file).

Durante l'elaborazione la pagina mostra l'avanzamento in tempo reale:

• Repository e Revision in lavorazione.
• Validation ID — l'identificativo univoco dell'esecuzione.
• State — evolve attraverso le fasi:
  PENDING → CLONING → DISCOVERING → VALIDATING → COMPLETED
  (oppure FAILED in caso di errore).
• Barra di progresso — indica gli asset analizzati nella forma «X / Y asset analizzati». Finché il totale degli asset non è noto (fase di clonazione o scoperta), viene mostrato un indicatore indeterminato.

Non è necessario tenere la pagina sempre in primo piano: lo stato viene aggiornato automaticamente fino al completamento.

3. Summary

Al termine viene mostrato un riepilogo aggregato con i contatori complessivi del report:

• numero di problemi Bloccanti, Warning e Migliorativi;
• numero totale di asset analizzati;
• numero di asset che presentano almeno un problema.

Il riepilogo offre una valutazione immediata dello stato di salute del repository.

4. Detailed report

La sezione finale consente di esplorare gli esiti nel dettaglio attraverso tre schede:

• Check repository — esiti dei controlli di conformità sulla struttura del repository (struttura directory, CI, hook di pre-commit).
• Validated assets — un elemento per ogni file .ttl scoperto, con i relativi problemi (sintassi e metadati), il percorso del file, il tipo di asset e l'indicazione se l'asset è stato saltato.
• JSON report — il report completo in formato JSON.

Sono disponibili filtri per severità (Bloccante, Warning, Migliorativo) e per tipo di asset, oltre a una ricerca per individuare rapidamente un asset.

Il pulsante «Esporta report (JSON)» permette di scaricare il report completo per archiviazione, confronto o analisi successive.

Tutti i problemi rilevati sono classificati secondo una tassonomia unificata a tre livelli:

I controlli sulla struttura del repository verificano in particolare:

• la presenza della directory assets/ e delle sottodirectory per tipo di asset
  (ontologies, controlled-vocabularies, schemas);
• l'assenza di strutture legacy non più supportate;
• la presenza della directory .github/workflows/ e del workflow validate.yaml, nonché il suo allineamento al template cookiecutter;
• la presenza del file .pre-commit-config.yaml e la copertura degli hook semantici pubblicati da dati-semantic-tools.

I check superati (PASSED) restano tracciati nel report a fini di rendicontazione, ma non incidono sui contatori del riepilogo.

Per ogni asset il report indica il path del file, il tipo
(ONTOLOGY / CONTROLLED_VOCABULARY / SCHEMA)
e la lista dei problemi.

Per i problemi di sintassi sono riportate, quando disponibili, riga e colonna;
per i problemi di metadati viene indicato il campo interessato (es. distributions).
Un asset marcato come saltato (skipped) non è stato validato fino in fondo, tipicamente perché un errore di sintassi ne ha impedito il parsing dei metadati.

Note e avvertenze

• Lo strumento valida esclusivamente repository GitHub pubblici; il formato atteso per gli asset è Turtle (.ttl).
• La validazione è a sola lettura: non modifica il repository né il catalogo. Può essere ripetuta liberamente.
• Per contenere il carico, il numero di validazioni eseguibili contemporaneamente è limitato:
  se il limite è saturo, la richiesta viene rifiutata con un messaggio che invita a riprovare tra qualche secondo.
• I risultati di una validazione restano disponibili per un tempo limitato (circa 30 minuti dall'ultimo accesso): trascorso tale periodo è necessario rilanciare la validazione. Se si prevede di consultarli in seguito, conviene esportare il report JSON.
• A parità di contenuto del repository, gli esiti prodotti da questo strumento sono equivalenti a quelli generati dal catalogo durante l'harvesting reale.
• La verifica si ferma al livello sintattico e dei metadati dichiarativi: non è prevista in questa fase la validazione semantica (SHACL / shape) degli asset.