1 — Come funziona il tool
Il tool trasforma un CSV della PA in RDF/Turtle (TTL) conforme alle ontologie di dati-semantic-assets. Non richiede installazione: è una singola pagina HTML che gira nel browser.
poi:PointOfInterest con clv:hasAddress. Se le ontologie sono sbagliate, il TTL sarà sbagliato: verificale sempre prima di generare.
2 — Partire da zero: costruire un CSV "decente"
Se la tua PA non ha ancora un CSV, segui questa metodologia per costruirne uno che generi un TTL completo e semanticamente ricco.
Passo 1 — Identifica il tipo di dataset
Prima di tutto: cosa stai pubblicando? Consulta il catalogo dei dataset ottimali e scegli il template più adatto al tuo caso.
| Tipo di dato | Ontologie principali | Colonne obbligatorie |
|---|---|---|
| Luoghi fisici (DAE, farmacie, uffici) | POI + CLV | nome, indirizzo, lat, lon |
| Organizzazioni, enti PA | COV + CLV | denominazione, codice_ipa, comune |
| Statistiche, dati aggregati | QB + CLV | anno, comune, valore numerico |
| Scuole, istituti | SMAPIT + CLV + SM | codice_meccanografico, nome_istituto, lat, lon, telefono |
| Strutture ricettive | ACCO + CLV | nome, stelle, posti_letto, indirizzo |
| Sensori / misure ambientali | IoT + CLV + POI + TI | stazione_id, data, lat, lon, valore_misurato |
| Fermate TPL | GTFS + CLV | stop_id, stop_name, stop_lat, stop_lon |
| Persone (anagrafe) | CPV + CLV | cognome, nome, codice_fiscale, comune |
Passo 2 — Scegli le intestazioni giuste
Le intestazioni delle colonne determinano tutto: il tool le riconosce e le mappa su proprietà ontologiche ufficiali. Usa i nomi standard riportati in questa guida (sezione Intestazioni chiave). Esempio per un dataset di defibrillatori:
Corretto: id,nome,indirizzo,modello,lat,lon,stato Evitare: ID,Nome_Punto,Luogo,Tipo_DAE,Latitudine,Longitudine,Funzionante
La seconda riga usa nomi non standard: il tool li metterà in rdfs:comment invece di proprietà ontologiche corrette.
Passo 3 — Includi sempre le coordinate
Se il tuo dataset ha una componente geografica (quasi sempre nella PA locale), includi lat e lon come colonne separate. Questo attiva automaticamente POI e CLV.
Evitare: geo_point 44.4938, 11.3430 <-- tutto in una cella, non riconosciuto Corretto: lat,lon 44.4938,11.3430 <-- due colonne separate, riconosciuto subito
Template CSV minimale per dataset POI (luoghi fisici)
id,nome,tipo,indirizzo,comune,lat,lon,telefono,email,note
1,Farmacia Centrale,farmacia,Via Roma 10,Bari,41.1171,16.8719,0801234567,farmacia@mail.it,aperta 24h
2,Defibrillatore Municipio,DAE,Piazza del Comune 1,Bari,41.1253,16.8620,,, funzionante
- id → identificatore univoco (usato per costruire l'URI RDF)
- nome →
rdfs:label— il nome leggibile del soggetto - tipo →
dct:type— categoria del punto di interesse - indirizzo →
clv:fullAddressnel nodoclv:Address - lat, lon →
geo:lat/geo:longcon tipoxsd:decimal - telefono →
sm:hasTelephone - email →
sm:hasEmailcon URImailto:
3 — Migliorare un CSV esistente
Hai già un CSV pubblicato e vuoi aumentare la qualità del TTL generato? Segui questa checklist.
Problemi frequenti nei CSV PA
- Coordinate in una sola cella ("44.56, 11.27")
- Intestazioni generiche (col1, col2, valore)
- Separatore ; invece di ,
- Encoding ISO-8859 invece di UTF-8
- Valori misti (numeri e testo nella stessa colonna)
- Colonna "id" con valori come 1, 2, 3 mappata su rdfs:label
- Indirizzo, via, comune, cap tutti in una colonna sola
Fix rapidi ad alto impatto
- Dividi "Geo Point" → colonne lat e lon separate
- Rinomina le intestazioni con i nomi standard (vedi tabella)
- Converti in UTF-8 da LibreOffice: Salva con nome → UTF-8
- Rinomina "id" in "codice" o "codice_identificativo"
- Separa indirizzo in: via, civico, comune, cap, provincia
- Aggiungi colonne lat/lon se hai indirizzi (geocodifica)
- Usa punto decimale, non virgola (40.604 non 40,604)
Come leggere gli avvisi gli avvisi del validatore
Dopo aver caricato il CSV, usa il pulsante "Valida". Gli avvisi indicano cosa migliorare:
| Avviso | Causa | Fix |
|---|---|---|
| Avviso: rdfs:label con valore numerico | Una colonna numerica finisce come etichetta | Rinomina la colonna o aggiungi una colonna "nome" testuale |
| Avviso: colonne non mappate non mappate → rdfs:comment | Intestazioni non standard | Rinomina con i nomi standard O usa l'AI (STEP 2) |
| Avviso: Colonna "Geo Point" con lat/lon unificati | Coordinate in una cella | Dividi in due colonne lat e lon |
| Errore Encoding problematico | File ISO-8859, non UTF-8 | Riesporta da Excel/LibreOffice scegliendo UTF-8 |
| Errore Coordinate fuori range | Virgola usata come decimale | Sostituisci , con . nei valori numerici |
rdfs:comment "COLONNA: valore"@it, significa che quelle colonne non sono state riconosciute. Rinominale con i nomi standard o attiva l'AI per gestirle.
4 — Quando conviene usare l'AI (STEP 2)
Il motore deterministico funziona istantaneamente e copre la grande maggioranza dei CSV PA standard. L'AI entra in gioco quando le colonne sono specifiche di dominio o non standard.
Copertura stimata del motore deterministico senza AI
Usa il deterministico (senza AI) quando:
- Il CSV usa intestazioni italiane standard (nome, indirizzo, lat, lon...)
- Il dataset è uno dei 39 tipi nel menu esempi
- Il validatore mostra 0 colonne non mappate
- Il TTL atteso ha < 50 triple per soggetto
- Vuoi velocità massima (generazione istantanea)
Quando attivare l'AI (STEP 2) (STEP 2) quando:
- Hai ≥ 3 colonne non mappate (avviso nel validatore)
- Le intestazioni sono abbreviazioni o codici (es. UO_AMM, COD_PRES)
- Il dominio è specifico (sanitario, agricolo, giudiziario)
- Vuoi la mappatura più precisa possibile
- Il CSV ha intestazioni in inglese o miste
5 — Intestazioni chiave riconosciute
Queste intestazioni vengono mappate automaticamente su proprietà ontologiche ufficiali. Usarle correttamente è il modo più semplice per ottenere un TTL ricco senza AI.
Colonne geografiche → CLV + POI
| Intestazione CSV | Proprietà RDF | Note |
|---|---|---|
lat / latitudine | geo:lat | Punto decimale, es. 41.117 |
lon / longitudine | geo:long | Punto decimale, es. 16.871 |
indirizzo | clv:fullAddress | Su nodo clv:Address |
comune | clv:hasCity | Skippa nella generazione URI |
citta / città | clv:hasCity | Alias di comune |
cap | clv:postCode | Codice postale |
codice_comune | dct:spatial | URI vocabolario comuni ISTAT |
Colonne organizzazione → COV
| Intestazione CSV | Proprietà RDF |
|---|---|
codice_ipa | cov:IPAcode |
partita_iva | cov:VATnumber |
ragione_sociale / denominazione | cov:legalName |
nome_centro / nome_struttura | cov:legalName |
forma_giuridica | cov:hasLegalStatus + URI vocabolario |
codice_ateco | cov:hasActivityType + URI vocabolario ATECO |
Contatti → SM
| Intestazione CSV | Proprietà RDF |
|---|---|
email | sm:hasEmail (URI mailto:) |
telefono / cellulare | sm:hasTelephone |
sitoweb / sito_web | sm:hasWebSite (URI) |
pec | sm:hasEmail |
Colonne temporali → TI
| Intestazione CSV | Proprietà RDF |
|---|---|
data | ti:startTime (xsd:date) |
data_inizio / inizio | ti:startTime |
data_fine / termine | ti:endTime |
data_nascita | cpv:dateOfBirth |
anno / mese | sdmx-dimension:refPeriod |
Colonne statistiche → QB
| Intestazione CSV | Proprietà RDF |
|---|---|
valore / numero / totale | sdmx-measure:obsValue |
popolazione_residente | sdmx-measure:obsValue |
kwh_prodotti / consumo_kwh | sdmx-measure:obsValue (ENER) |
feriti / morti | sdmx-measure:obsValue (JUST) |
numero_alunni | sdmx-measure:obsValue (EDUC) |
superficie_ha | sdmx-measure:obsValue (AGRI) |
Colonne sensori → IoT
| Intestazione CSV | Proprietà RDF |
|---|---|
pm10 / pm25 / no2 / so2 | iot:hasValue (xsd:decimal) |
temperatura_c / umidita_perc | iot:hasValue |
precipitazioni_mm / pressione_hpa | iot:hasValue |
stazione_id / nome_stazione | trigger POI (centralina geolocalizzata) |
unita_misura | mu:hasMeasurementUnit |
6 — Metodologia: come funziona il motore
Rilevamento ontologie deterministico
Il motore analizza le intestazioni del CSV (header) e i valori delle prime righe, poi applica una cascata di regole per determinare quali ontologie usare. Le ontologie rilevate comandano la generazione TTL.
Principi chiave del rilevamento:
- CLV scatta se ci sono colonne geografiche (lat, lon, comune, indirizzo...)
- POI scatta se ci sono coordinate + nome del luogo
- IoT→POI e IoT→TI scattano automaticamente (sensori geolocalizzati hanno sempre coordinate e timestamp)
- QB richiede colonne numeriche aggregate + anno/periodo, ma non scatta su eventi puntuali con data+ora+lat
- ACCO non scatta se il CSV è di strutture socioassistenziali (RSA, centri diurni)
- SM scatta automaticamente se ci sono colonne telefono/email
Corpus di riconoscimento (330 fixture)
Il motore usa un corpus di 330 pattern estratti da CSV reali della PA italiana, organizzati per i 13 temi DCAT. Ogni fixture contiene header tipici e valori di esempio che guidano il rilevamento per dataset ambigui.
Ontologie e vocabolari controllati ufficiali
Il tool usa esclusivamente le ontologie del progetto dati-semantic-assets (ex OntoPiA), verificate sui TTL ufficiali scaricati da daf-ontologie-vocabolari-controllati. I valori classificabili vengono tipizzati con URI dai vocabolari controllati di schema.gov.it (336 risorse analizzate).
# Esempio: forma_giuridica genera URI tipizzato <...> cov:hasLegalStatus <https://w3id.org/italia/controlled-vocabulary/classifications-for-organizations/legal-status/comune> . # Invece di una stringa generica <...> dct:type "Comune"@it .
Struttura degli URI RDF generati
# Pattern URI standard https://w3id.org/italia/data/{ipa}/{tipo-entità}/{id-riga} # Esempi concreti https://w3id.org/italia/data/c_a662/point-of-interest/1 https://w3id.org/italia/data/c_a662/address/1 https://w3id.org/italia/data/r_emiro/public-organization/AOU-Policlinico
Il tipo-entità dipende dall'ontologia principale: point-of-interest per POI, public-organization per COV, observation per QB, sensor per IoT, ecc.
7 — Errori comuni e come evitarli
Problema: CSV con "Geo Point" unificato
Geo Point
"44.56268, 11.27106"
Il tool mostra avviso (triangolo). Soluzione: dividi in due colonne separate lat e lon in Excel con Dati → Testo in colonne, usando la virgola come delimitatore.
Problema: Nessuna colonna "nome" o "denominazione"
id,tipo,lat,lon
1,DAE,41.117,16.871
Senza etichetta leggibile il TTL genera rdfs:label "1"@it — numerico. Aggiungi una colonna nome con testo descrittivo.
Problema: Separatore ; con portali regionali
Molti portali open data italiani esportano CSV con ; come separatore. Il tool lo gestisce automaticamente, ma il validatore mostra un avviso informativo. Nessuna azione richiesta se l'avviso è info (blu), non errore (rosso).
Attenzione: Posti letto ≠ struttura ricettiva
nome_struttura,tipo_struttura,posti_letto
RSA San Giuseppe,RSA,80
posti_letto di solito attiva ACCO (strutture ricettive), ma una RSA non è un hotel. Il tool v88 riconosce tipo_struttura + nome_struttura come struttura sociale e usa COV+POI invece di ACCO.
Attenzione: codice_istat blocca le statistiche
In versioni precedenti codice_istat bloccava il rilevamento QB. Dalla v85 questo è risolto: i CSV demografici con codice_istat vengono riconosciuti correttamente come QB+CLV.
Link dati.gov.it migliora il detect
Se il tuo dataset è già pubblicato su dati.gov.it, incolla il link nello STEP 1 BIS. Il tool legge i temi DCAT (themes_aggregate) e li usa per escludere ontologie spurie e suggerire quelle corrette. Esempio: tema HEAL suggerisce POI+CLV+SM e scarta GTFS/ACCO.
nome/denominazione (etichetta testuale), indirizzo o lat+lon (localizzazione), tipo (categoria), e un identificatore univoco. Con queste quattro il tool genera TTL valido anche senza AI.