Questa pagina è stata tradotta dall'API Cloud Translation.

Guida per gli sviluppatori DSPL

DSPL è l'acronimo di Dataset Publishing Language. Si tratta di un formato di rappresentazione sia per i metadati (informazioni sul set di dati, come il nome e il provider, nonché per i concetti che contiene e visualizza) e per i dati effettivi dei set di dati. I set di dati descritti in questo formato possono essere importati in Google Public Data Explorer, uno strumento che consente di eseguire un'esplorazione visiva e approfondita dei dati.

Nota: per caricare i dati in Google Public Data utilizzando lo strumento di caricamento dei dati pubblici, devi avere un Account Google.

Questo documento è destinato ai proprietari dei dati che vogliono che i loro contenuti siano disponibili in Public Data Explorer. Non si limita al tutorial, ma approfondisce i dettagli dello schema DSPL e delle funzionalità supportate. Si presume solo una conoscenza di base del linguaggio XML, anche se è utile anche conoscere i database relazionali.

Sebbene non sia un requisito, ti consigliamo di leggere il tutorial, più breve e di facile comprensione, prima di consultare questo documento.

Panoramica

Un set di dati DSPL è un file ZIP contenente un file XML e un insieme di file CSV. I file CSV sono semplici tabelle contenenti i dati del set di dati, mentre il file XML descrive i metadati del set di dati. Quest'ultimo include metadati informativi come le descrizioni delle misure, nonché metadati strutturali come i riferimenti tra tabelle. Questi metadati consentono agli utenti non esperti di esplorare e visualizzare i tuoi dati.

Processo

In generale, la procedura per creare un set di dati DSPL è la seguente (alcuni passaggi possono essere eseguiti in parallelo):

Crea il file XML di DSPL.
Identifica eventuali origini dati esterne da utilizzare nel tuo set di dati.
Definisci i concetti, le sezioni e, in via facoltativa, gli argomenti. Aggiorna in modo iterativo i contenuti del file DSPL.
Esporta i dati di origine in file .csv.
Creare un set di dati DSPL.
Invia il set di dati a Google.

Struttura XML

Panoramica

Il file XML di DSPL definisce i metadati del set di dati, comprese le relazioni strutturali tra concetti, sezioni, argomenti e tabelle. Sebbene sia possibile creare questo file manualmente, gli strumenti e gli script per l'elaborazione dei dati possono semplificare notevolmente il processo. Visualizza un file DSPL di esempio in una nuova finestra.

Il file include una serie di sezioni, riassunte nella tabella. Seguendo la tabella, descriviamo ogni dettaglio in modo più dettagliato.

Sezione	Riepilogo	Ulteriori informazioni
Intestazione e importazioni	L'elemento principale per tutti gli altri elementi del set di dati. Include lo spazio dei nomi di destinazione (ovvero l'identificatore) per il set di dati, insieme agli spazi dei nomi di eventuali set di dati importati.	Documentazione
Informazioni sul set di dati	Il nome, la descrizione e l'URL del set di dati.	Documentazione
Informazioni del Fornitore	Il nome, la descrizione e l'URL del fornitore del set di dati.	Documentazione
Concetti	Definizioni di "cose" che compaiono nel set di dati (ad es. paesi, tasso di disoccupazione, genere ecc.) Ogni concetto ha un identificatore univoco a cui è possibile fare riferimento in sezioni e tabelle.	Documentazione
Sezioni	Combinazioni di concetti per i quali sono disponibili dati statistici nel set di dati. Ogni sezione contiene dimensioni e metriche. Sezioni che fanno riferimento a concetti e tabelle che contengono i dati effettivi. Ogni sezione ha un identificatore univoco a cui possono fare riferimento le tabelle contenenti i dati effettivi.	Documentazione
Tabelle	Definisci i dati per concetti e sezioni. Le tabelle dei concetti contengono enumerazioni e le tabelle delle sezioni contengono dati statistici. Le tabelle sono definite nel file XML e rimandano ai file .csv contenenti i dati effettivi.	Documentazione
Argomenti	Categorie per l'organizzazione dei concetti dei set di dati. Sebbene non siano obbligatori, possono essere molto utili per gli utenti che navigano nei dati.	Documentazione

Intestazione e importazioni

Dichiarazione dello spazio dei nomi di dati pubblici

Un set di dati DSPL inizia con un elemento <dspl> di primo livello. Utilizzato per includere tutte le informazioni del set di dati e per indicare gli spazi dei nomi che verranno utilizzati durante il file. Ad esempio:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.example.com/mystats"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://schemas.google.com/dspl/2010" >
    ...
</dspl>

Uno spazio dei nomi è un identificatore univoco che può essere associato a uno schema XML (un insieme di elementi e attributi XML). targetNamespace fornisce un URI che identifica il tuo set di dati. Questo URI non è obbligatorio per puntare a una risorsa effettiva, ma è consigliabile che l'URI venga risolto in un documento che descriva i tuoi contenuti o set di dati.

Non è necessario fornire un targetNamespace. In caso contrario, ne verrà generato automaticamente uno al momento dell'importazione.

L'attributo targetNamespace è seguito da una serie di attributi xmlns che specificano altri schemi XML che verranno utilizzati nel file. Ogni file DSPL deve includere lo schema dei dati pubblici di Google, il cui URI è "http://schemas.google.com/dspl/2010" e utilizzarlo come spazio dei nomi predefinito. Deve includere anche lo schema XML W3 standard, identificato da "http://www.w3.org/2001/XMLSchema-instance". Come descritto nella sezione successiva, è possibile aggiungere altri spazi dei nomi per includere informazioni provenienti da altri set di dati.

Importazione di altri spazi dei nomi del set di dati

I set di dati possono riutilizzare definizioni e dati di altri set di dati. Google, ad esempio, fornisce una serie di set di dati di base che definiscono concetti comunemente visualizzati nei dati utente. Ad esempio, la maggior parte dei set di dati ha bisogno di un concetto per rappresentare gli anni. Invece di definire un nuovo concetto, puoi utilizzare il concetto dell'anno dal set di dati "http://www.google.com/publicdata/dataset/time". Per ulteriori informazioni, consulta la pagina Concetti canonici.

Per utilizzare un set di dati esterno, aggiungi l'elemento <import> al file DSPL subito dopo la dichiarazione dello spazio dei nomi e indica lo spazio dati che stai importando, in questo modo:

<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Quindi, aggiungi lo spazio dei nomi importato (in questo caso, time="http://www.google.com/publicdata/dataset/google/time") nella dichiarazione dello spazio dei nomi nella parte superiore del file, in questo modo:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.stats-bureau.com/mystats"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://schemas.google.com/dspl/2010"
    xmlns:time="http://www.google.com/publicdata/dataset/google/time" >
<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Il file DSPL può ora fare riferimento agli elementi del set di dati relativi al tempo di Google Public Data. Ripeti questa procedura per ogni set di dati a cui vuoi fare riferimento.

Fare riferimento a contenuti in set di dati esterni

Dopo aver importato un altro set di dati, devi poter fare riferimento a concetti, sezioni e dati di tale set di dati. A questo scopo, puoi utilizzare i riferimenti nel formato prefix:other_id, dove prefix è il prefisso utilizzato per lo spazio dei nomi del set di dati esterno.

Ecco un esempio di riferimento al concetto year dal set di dati time (descritto sopra):

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Informazioni su set di dati

L'elemento <info> include informazioni descrittive sul set di dati. Di seguito sono riportati un esempio e i dettagli relativi agli elementi XML pertinenti.

Esempio

<info>
  <name>
    <value>Unemployment Rates</value>
  </name>
  <description>
    <value>Worldwide unemployment rates by region</value>
  </description>
  <url>
    <value>http://www.example.com/mystats/info.html</value>
  </url>
</info>

Elementi

Elemento	Obbligatoria?	Descrizione
`<info>`	Sì	Include tutte le informazioni descrittive sul set di dati. Include gli elementi secondari `<name>`, `<description>` e `<url>`.
`<name>`	Sì	Figlio di `<info>`. Include l'elemento secondario `<value>`, che identifica il nome del set di dati.
`<description>`	Facoltativo	Figlio di `<info>`. Include l'elemento secondario `<value>`, che include una descrizione testuale del set di dati.
`<url>`	Sì	Figlio di `<info>`. Un link all'URL con ulteriori informazioni sul set di dati.

Informazioni sul fornitore

L'elemento <provider> elenca le informazioni sul provider del set di dati. Di seguito sono riportati un esempio e i dettagli relativi agli elementi XML pertinenti.

Esempio

<provider>
  <name>
    <value>Bureau of Statistics</value>
  </name>
  <url>
    <value>http://www.example.com</value>
  </url>
</provider>

Elementi

Elemento	Obbligatoria?	Descrizione
`<provider>`	Sì	Include tutte le informazioni descrittive sul provider del set di dati. Include gli elementi secondari `<name>` e `<url>`.
`<name>`	Facoltativo	Figlio di `<provider>`. Include l'elemento secondario `<value>`, che identifica il nome del provider del set di dati.
`<url>`	Facoltativo	Figlio di `<info>`. Un link a un URL con ulteriori informazioni sul provider del set di dati.

Concetti

Descrizione

Ogni set di dati contiene uno o più concetti. Un concetto è una definizione di un tipo di dati che viene visualizzato in un set di dati. Ad esempio, un set di dati con dati demografici sulla popolazione potrebbe includere i concetti relativi a paese, stato, popolazione e anno. I valori dei dati corrispondenti a un determinato concetto sono chiamati istanze. I concetti sono generalmente descritti nel set di dati, ma alcuni concetti (come ora o anno) possono essere descritti in set di dati esterni.

Ogni concetto può avere una o più proprietà. Una proprietà è una caratteristica di un'istanza concettuale stabile nel tempo. Ad esempio, il concetto di paese potrebbe avere le proprietà name, population e capital.

I concetti possono anche avere uno o più attributi. Gli attributi forniscono informazioni a livello di concetto, non delle singole istanze. Ad esempio, se avessimo un set di dati con un concetto basato sul tasso di disoccupazione, potremmo utilizzare un attributo per indicare che si tratta di una percentuale. Un altro esempio comune dell'utilizzo degli attributi consiste nel fornire informazioni sull'unità.

Esempio

Di seguito è riportato un esempio di concetto di paese con ID univoco country e proprietà name. L'ID concetto può essere utilizzato per fare riferimento al concetto da sezioni e tabelle.

<concept id="country" extends="geo:location">
  <info>
    <name><value>Country</value></name>
    <description>
      <value>My list of countries.</value>
    </description>
  </info>
  <type ref="string"/>
  <property id="name">
    <info>
      <name><value>Name</value></name>
      <description>
        <value>The official name of the country</value>
      </description>
    </info>
    <type ref="string" />
  </property>
  <property concept="geo:continent" isParent="true"/>
  <property id="capital" concept="geo:city" />
  <table ref="countries_table" />
</concept>

Ecco come funziona questo codice di esempio.

Questo codice descrive il paese del concetto, che ha l'ID country e le proprietà name, continent e capital.
Il concetto estende geo:location, il concetto canonico delle località. Se estendi geo:location, country eredita tutte le proprietà e gli attributi definiti dal concetto esteso: nome, descrizione, URL, latitudine e longitudine delle proprietà. country può ridefinire alcuni di questi attributi e proprietà, purché la definizione sia coerente con quella fornita dal concetto esteso.
L'elemento concetto <info> descrive le informazioni chiave sul concetto. Viene visualizzato nella pagina di destinazione del set di dati in Public Data Explorer.
Il concetto di elemento <type> fa riferimento al tipo di contenuti. In questo caso è una stringa, ma può variare. Il tipo di popolazione dovrebbe essere di tipo integer, mentre il concetto di Eurovision winner potrebbe essere di tipo booleano.
Un elemento <property> descrive ogni proprietà del concetto, inclusi l'ID univoco (id), info e type. Le proprietà possono anche fare riferimento a concetti per indicare che i relativi valori sono istanze valide di tali concetti.
Il concetto fa riferimento a una tabella di dati che indirizza al file CSV contenente i dati effettivi. Il riferimento alla tabella dati è: <table ref="countries_table"/>.

Se il concetto fa riferimento a una tabella, il file di dati associato deve elencare tutte le istanze del concetto. Ad esempio, non puoi creare una tabella che elenca solo alcuni dei paesi inclusi nel set di dati. Se c'è un sottoinsieme di paesi a cui tieni, puoi creare un concetto a parte per descriverli. ad esempio mycountries).

Elementi

Elemento	Obbligatoria?	Descrizione
`<concepts>`	Sì	Elemento di primo livello. Comprende tutti gli elementi `<concept>`.
`<concept>`	Sì	Identifica il concetto. Il valore dell'attributo obbligatorio `id` deve essere univoco per il concetto all'interno del set di dati. Se il concetto fa riferimento a una tabella di dati, il valore di `id` deve corrispondere all'intestazione della colonna che descrive il concetto nella tabella dei dati. È possibile utilizzare un attributo `extends` per indicare che questo concetto estende un altro concetto. Il valore di `extends` deve corrispondere all'ID di un concetto definito nello stesso set di dati oppure essere nel formato `prefix:concept_id`, dove `concept_id` è l'ID di un concetto definito nel set di dati esterno importato associato a `prefix`.
`<info>`	Facoltativo	Include informazioni descrittive sul concetto.
`<name>`	Sì	Figlio di `<info>`. Il nome del concetto. L'elemento secondario `<value>` contiene il testo, ad esempio `Country`.
`<description>`	Facoltativo	Figlio di `<info>`. Include l'elemento secondario `<value>`, che include una descrizione testuale del concetto.
`<url>`	Facoltativo	Figlio di `<info>`. Include l'elemento secondario `<value>`, che include un URL per il concetto.
`<pluralName>`	Facoltativo	Figlio di `<info>`. Il nome plurale del concetto. L'elemento secondario `<value>` contiene il testo, ad esempio `Countries`.
`<totalName>`	Facoltativo	Figlio di `<info>`. Il nome della combinazione di tutte le istanze del concetto. L'elemento secondario `<value>` contiene il testo. Nel caso del concetto `country`, ad esempio, potrebbe essere `World`.
`<type>`	Facoltativo	Identifica il tipo di contenuti descritto dal concetto. L'attributo obbligatorio `ref` ha i seguenti valori consentiti: string numero in virgola mobile integer date boolean Il tipo può essere omesso se il concetto estende un altro concetto, nel qual caso è ereditato dal concetto esteso.
`<property>`	Facoltativo	Una proprietà del concetto, ad esempio `capital`. Il valore dell'attributo obbligatorio `id` deve essere univoco per il concetto. È possibile utilizzare un attributo `concept` facoltativo per indicare che i valori di questa proprietà sono istanze di un determinato concetto. Se `concept` è specificato, `id` può essere omesso; il suo valore è definito implicitamente come ID del concetto a cui viene fatto riferimento (ad esempio `<property concept="geo:country"/>` equivale a `<property id="country" concept="geo:country"/>`). Una proprietà può contenere un attributo `isParent` booleano, per indicare che la relazione tra un'istanza del concetto e il valore di questa proprietà è gerarchica. Una proprietà può contenere un attributo `isMapping` booleano, per indicare che esiste una mappatura 1-1 tra le istanze del concetto e i valori della proprietà. Una proprietà può specificare `info` e `type` nidificati, che vengono definiti esattamente come per un concetto. `type` è obbligatorio se la proprietà non specifica un attributo `concept` e, in tal caso, deve corrispondere al tipo di concetto a cui viene fatto riferimento.
`<attribute>`	Facoltativo	Un attributo del concetto. Gli attributi rappresentano informazioni aggiuntive sul concetto (ad es. PIL è una percentuale). Il valore dell'attributo obbligatorio `id` deve essere univoco per il concetto. È possibile utilizzare un attributo `concept` facoltativo per indicare che i valori di questo attributo sono istanze di un determinato concetto. Se `concept` è specificato, `id` potrebbe essere omesso. Il suo valore è implicitamente definito come l'ID del concetto a cui si fa riferimento. (ad es. `<attribute concept="unit:unit"/>` equivale a `<attribute id="unit" concept="unit:unit"/>`. Un attributo può specificare `info` e `type` nidificati, definiti proprio come per un concetto. `type` è obbligatorio se l'attributo non specifica un attributo `concept` e, in tal caso, deve corrispondere al tipo di concetto indicato.
`<table>`	Facoltativo	Identifica la tabella contenente i dati per il concetto. Il valore dell'attributo `ref` obbligatorio deve corrispondere all'ID tabella specificato nell'elemento `<table>` correlato.

Sezioni

Descrizione

Una sezione è una combinazione di concetti per i quali esistono dati. Una sezione contiene due tipi di riferimenti a concetti: dimensioni e metriche. Una dimensione è un concetto utilizzato per segmentare o filtrare i dati. Una metrica, invece, descrive il valore o i valori osservati associati a ogni punto dati.

In genere, le dimensioni sono categoriche, mentre le metriche non sono categoriche, i valori numerici sono variabili in base all'ora. Ecco alcuni esempi prototipici:

Dimensioni: paese, stato, contea, regione, anno, mese, genere, categoria di età, segmento di settore
Metriche: popolazione, PIL, tasso di disoccupazione, alfabetizzazione, entrate, costo, prezzo

Esempio

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Ecco come funziona questo codice di esempio.

Questa sezione rappresenta la popolazione per paese.
Ha la metrica population e le dimensioni country e year. Ogni dimensione è un concetto già definito altrove. Il concetto country e la metrica population esistono nello stesso set di dati della sezione attuale e vi viene fatto riferimento in questo modo: concept="country"
Il concetto year esiste nel tempo del set di dati importato, identificato dal prefisso utilizzato prima del nome del concetto (year), come segue: concept="time:year"
La sezione fa riferimento a una tabella di dati che rimanda al file CSV contenente i dati effettivi. Il riferimento alla tabella dati è il seguente: <table ref="country_slice_table"/>. (vedi sopra per informazioni sull'importazione di set di dati).

Nota: in generale, il set di dati sarà più flessibile se mantieni le metriche al minimo e crei dimensioni significative. Ad esempio, anziché creare le metriche Female Unemployment e Male Unemployment, crea la singola metrica Unemployment e aggiungi la dimensione Gender che contiene le istanze Female e Male.

Elementi

Elemento	Obbligatoria?	Descrizione
`<slices>`	Sì	Elemento di primo livello. Comprende tutti gli elementi `<slice>`.
`<slice>`	Facoltativo	Identifica la sezione. Il valore dell'attributo obbligatorio `id` deve essere univoco per la porzione.
`<dimension>`	Facoltativo	Definisce una dimensione della sezione, facendo riferimento a un concetto. Il valore dell'attributo obbligatorio `concept` deve corrispondere esattamente all'ID univoco del concetto e utilizzare un prefisso valido se il concetto appartiene a un set di dati importato esternamente.
`<metric>`	Facoltativo	Definisce una metrica della sezione facendo riferimento a un concetto. Il valore dell'attributo obbligatorio `concept` deve corrispondere esattamente all'ID univoco del concetto e utilizzare un prefisso valido se il concetto appartiene a un set di dati importato esternamente.
`<table>`	Sì	Identifica la tabella contenente i dati per la sezione. Il valore dell'attributo `ref` obbligatorio deve corrispondere all'ID tabella specificato nell'elemento `<table>` correlato.
`<mapDimension>`	Facoltativo	Figlio di `<table>`. Contiene gli attributi `concept` e `toColumn`; il valore del primo è una dimensione nella porzione, mentre il valore del secondo è la colonna della tabella corrispondente al primo.
`<mapMetric>`	Facoltativo	Figlio di `<table>`. Contiene gli attributi `concept` e `toColumn`; il valore del primo è una metrica nella porzione, mentre il valore del secondo è la colonna della tabella corrispondente al primo.

Tabelle

Descrizione

La sezione tables del file DSPL identifica le tabelle di dati incluse nel set di dati. È possibile fare riferimento a queste tabelle tramite concetti o per sezioni. Ogni elemento <table> specifica le colonne delle tabelle e i relativi tipi e rimanda a un file CSV contenente i dati della tabella.

Esempio

<tables>
  <table id="country_slice_table">
    <column id="country" type="string"/>
    <column id="year" type="date" format="yyyy"/>
    <column id="population" type="integer"/>
    <data>
      <file format="csv" encoding="utf-8">country_slice.csv</file>
    </data>
  </table>
  ...
</tables>

Ecco come funziona questo codice di esempio.

Questo esempio descrive la tabella country_slice_table. La tabella ha le colonne country, year e population.
Ogni colonna nella tabella ha un ID univoco, definito dall'attributo id. Questo ID deve corrispondere esattamente all'intestazione della colonna appropriata nel file di dati associato.
Il valore dell'attributo facoltativo type definisce il tipo di dati per ogni colonna.
L'elemento <data> descrive il file .csv effettivo (country_slice.csv) contenente i dati della tabella. Il formato file è sempre csv.

Elementi

Elemento	Obbligatoria?	Descrizione
`<tables>`	Sì	Elemento di primo livello. Comprende tutti gli elementi `<table>`.
`<table>`	Sì	Identifica la tabella. Il valore dell'attributo obbligatorio `id` deve essere univoco per la tabella.
`<column>`	Facoltativo	Figlio di `<table>`. Informazioni su una colonna inclusa nella tabella. Include i seguenti attributi: `id` (obbligatorio): l'ID della colonna. (Facoltativo) `type`: il tipo di dati delle informazioni nella colonna specificata. I valori consentiti sono: `string`, `float`, `integer`, `date` o `boolean`.
`<data>`	Facoltativo	Figlio di `<table>`. Il file di dati a cui viene fatto riferimento nella tabella. Se il nome del file è sotto forma di URL (ad es. `http://...`), il file verrà recuperato tramite il protocollo appropriato (HTTP, HTTPS o FTP); in caso contrario, il file con il nome specificato deve essere incluso nel set di dati. Il valore dell'attributo obbligatorio `format` è sempre `csv`. Anche se l'attributo `encoding` è facoltativo, i file .csv devono avere la codifica UTF-8.

Argomenti

Descrizione

Topics classifica i concetti in modo gerarchico, consentendo agli utenti di navigare più facilmente nel tuo set di dati.

L'elemento <topics> dovrebbe apparire subito prima dell'elemento <concepts> nel file DSPL. L'ordine degli elementi è importante e potresti non riuscire a caricare il set di dati se gli elementi vengono visualizzati nell'ordine sbagliato. Per usarli, fai riferimento a essi nella definizione del concetto.

Esempio

Di seguito è riportato un esempio di definizione di argomento:

<topics>
  <topic id="population_indicators">
    <info>
      <name>
        <value>Population indicators</value>
      </name>
    </info>
  </topic>
  ...
</topics>

...ecco un esempio di riferimento a questo argomento partendo da un concetto:

<concept id="population">
  <info>
    <name>
      <value>Population</value>
    </name>
    <description>
      <value>Size of the resident population.</value>
    </description>
  <topic ref="population_indicators"/>
  <type ref="integer"/>
</concept>

Gli argomenti possono essere nidificati e un concetto può fare riferimento a più di un argomento.

Definizione dell'elemento

Elemento	Obbligatoria?	Descrizione
`<topics>`	Sì	Elemento di primo livello. Comprende tutti gli elementi `<topic>`.
`<topic>`	Sì	Identifica l'argomento. Il valore dell'attributo obbligatorio `id` deve essere univoco per il set di dati.
`<info>`	Facoltativo	Figlio di `<topic>`. Contiene informazioni su un argomento.
`<name>`	Facoltativo	Figlio di `<info>`. L'elemento secondario `<value>` specifica il nome dell'argomento.

File di dati DSPL

Oltre al file metadati XML, un set di dati DSPL può includere anche uno o più file di dati in formato CSV. Ogni file di dati supporta una tabella nel set di dati e fa riferimento al precedente nella sezione <data>...</data>. Concettualmente, questi file e le tabelle associate vengono utilizzati per rappresentare le definizioni di concetti o i dati della sezione. Ciascuno di questi tipi di file di dati è descritto più dettagliatamente di seguito.

Tieni presente che, indipendentemente dallo scopo, tutti i file di dati devono essere file di testo UTF-8 delimitati da virgole (CSV). I file devono contenere solo testo normale, non HTML. Puoi creare i file di dati manualmente, ma in realtà dovrai massaggiare i dati nello strumento contenente l'origine dati originale (ad esempio, un foglio di lavoro) o nel file esportato stesso.

I file possono essere abbinati al set di dati oppure, se il nome è sotto forma di URL, viene recuperato tramite HTTP, HTTPS o FTP da una sorgente remota.

File di dati sui concetti

I file di dati dei concetti contengono informazioni pertinenti per ogni concetto. La definizione del concetto utilizza l'elemento <table> per fare riferimento a questo file.

Esempio

Ecco un esempio di tabella per il concetto country definito sopra:

country, name
AD, Andorra
AF, Afghanistan
AI, Anguilla
AL, Albania
AO, Angola
AQ, Antarctica
AS, American Samoa

Ecco come funziona questo esempio:

A meno che non siano specificate le mappature, la prima riga del file di dati (intestazioni delle colonne) deve corrispondere esattamente all'ID concetto e agli ID proprietà appropriati del concetto a cui sono associati i dati. Tuttavia, l'ordine delle colonne non deve essere necessariamente lo stesso nel file di dati e nella tabella concettuale. In questo caso, la prima colonna è associata al concetto country e la seconda è associata alla proprietà name.
Le colonne della proprietà sono facoltative; se una proprietà non ha una colonna nella tabella, si presume che il suo valore non sia definito per ogni riga. Nella tabella riportata sopra, ad esempio, vengono omesse le colonne per le proprietà latitude e longitude, quindi i paesi non saranno mappabili.
Ogni valore del campo ID del concetto (in questo caso, country) deve essere univoco e non vuoto (un campo vuoto è uno con zero o solo spazi vuoti).
I valori delle proprietà che fanno riferimento ad altri concetti devono essere vuoti o essere un valore valido per il concetto a cui si fa riferimento.
Il testo tra virgolette è facoltativo, tranne se contiene virgole, virgolette doppie o caratteri di nuova riga.
Esegui l'escape di una citazione doppia letterale che compare in un valore anteponendola a un'altra.

Sezione dati file

I file di dati della sezione contengono dati pertinenti per ogni porzione. La definizione della porzione utilizza l'elemento <table ref="..."> per fare riferimento alla definizione di <table>, che a sua volta identifica questo file.

Esempio

Di seguito è riportato un esempio di un file .csv contenente i dati della sezione population_by_country descritta sopra:

country, year, population
AF, 1960, 9616353
AF, 1961, 9799379
AF, 1962, 9989846
AF, 1963, 10188299

Ecco come funziona l'esempio:

Il campo della metrica è population. I campi country e year sono campi di dimensione.
Il valore di un campo dimensione non può essere vuoto. incluse le dimensioni temporali. I valori dei campi delle metriche possono essere vuoti. Un valore vuoto è rappresentato da un carattere.
Ogni intestazione di colonna che fa riferimento a un concetto (ad esempio, il primo campo dell'esempio precedente fa riferimento al concetto country) deve corrispondere esattamente all'ID univoco del concetto nella definizione del concetto.
Una combinazione unica di valori di dimensione, ad esempio AF, 2000, può verificarsi una sola volta.
Le righe nella stessa serie temporale (ovvero le righe che hanno la stessa combinazione di tutti i valori di dimensione, ad eccezione dell'ora), devono essere raggruppate, anche se non è necessario ordinarle.

Funzionalità avanzate

Set di dati multilingue

Valori XML tradotti

Puoi utilizzare l'attributo xml:lang con ogni elemento <value> nel file DSPL. Questo attributo specifica la lingua dei contenuti dell'elemento, utilizzando i tag della lingua standard W3C. Tieni presente che l'utilizzo di questa funzionalità è facoltativo. Se non è incluso alcun attributo xml:lang, si presume che i contenuti siano in inglese.

L'esempio riportato di seguito mostra le estensioni di un set di dati in inglese, bulgaro, catalano e cinese semplificato:

<dspl ...>
  <info>
    <name>
      <value xml:lang="en">World Bank, World Development Indicators</value>
      <value xml:lang="bg">Световна банка, Индикатори за световно развитие</value>
      <value xml:lang="ca">Banc Mundial, Indicadors del desenvolupament mundial</value>
      <value xml:lang="zh-CN">国家/地区</value>
    </name>
    ...
  </info>

  <concepts>
    <concept id="country">
      <info>
        <name>
          <value xml:lang="en">Country</value>
          <value xml:lang="bg">Страна</value>
          <value xml:lang="ca">País</value>
          <value xml:lang="zh-CN">国家/地区</value>
        </name>
        ...
      </info>
      ...
    </concept>
    ...
  </concepts>

  ...
</dspl>

Proprietà tradotte

In alcuni casi, potresti voler fornire traduzioni che vadano oltre i metadati a livello di concetto, applicando in aggiunta (o anziché) a singole istanze di concetto. Ciò è particolarmente utile quando i valori di una proprietà concettuale (ad es. il nome) variano in base alla lingua.

Per fornire tali valori in più lingue, crea una colonna nella tabella di definizione corrispondente per ogni combinazione proprietà/lingua. Collega queste colonne alle proprietà e alle lingue associate aggiungendo un insieme di elementi <mapProperty xml:lang="..." ref="..." toColumn="..."> al tag di riferimento della tabella per il concetto.

Ecco un esempio che definisce un concetto di paese con nomi in inglese, spagnolo e francese:

<concepts>
  ...
  <concept id="country" extends="geo:location">
    ...
    <property id="name">
      <info>
        <name>
          <value>Name</value>
        </name>
        <description>
          <value>The official name of the country</value>
        </description>
      </info>
      <type ref="string" />
    </property>
    ...
    <table ref="countries_table">
      <mapProperty xml:lang="en" ref="name" toColumn="name_en"/>
      <mapProperty xml:lang="es" ref="name" toColumn="name_es"/>
      <mapProperty xml:lang="fr" ref="name" toColumn="name_fr"/>
    </table>
  </concept>
  ...
</concepts>

...

<tables>
  ...
  <table id="countries_table">
    <column id="country" type="string"/>
    <column id="name_en" type="string"/>
    <column id="name_es" type="string"/>
    <column id="name_fr" type="string"/>
    ...
  </table>
</tables>

Il file CSV per countries_table avrà quindi il seguente formato:

country,name_en,name_es,name_fr,...
...
US,United States of America,Estados Unidos de América,États-Unis d'Amérique,...
...

Concetti mappabili

Molti concetti (ad esempio contea, stato e città) hanno istanze corrispondenti a località geografiche. DSPL supporta la geocodifica di queste istanze in modo che siano visualizzabili nel grafico mappa animato dei dati di Google Public.

Se il tuo concetto equivale a paesi del mondo, stati USA o contee statunitensi, puoi semplicemente collegarti al concetto canonico di Google corrispondente; non è richiesta alcuna geocodifica esplicita. Per ulteriori dettagli, consulta la Guida ai concetti canonici.

In caso contrario, devi rendere il tuo concetto mappabile. Il primo passaggio consiste nell'estenderlo da geo:location:

<concept id="..." extends="geo:location">
  ...
</concept>

Successivamente, devi aggiungere esplicitamente la latitudine e la longitudine come proprietà:

<concept id="..." extends="geo:location">
  ...
  <property id="latitude"/>
  <property id="longitude"/>
</concept>

I valori di questi valori vengono quindi specificati come colonne nella tabella dei dati di definizione del concetto corrispondente.

Relazioni con i concetti

Spesso i concetti sono correlati ad altri in modo strutturato. Ad esempio, un'istanza di un continente può includere più istanze di paese, che a loro volta possono contenere più istanze di stato o provincia. La codifica di queste relazioni nei metadati del set di dati consente di avere funzionalità di visualizzazione più dettagliate di quelle che sarebbero altrimenti possibili, ad esempio la visualizzazione di un albero comprimibile di località tra cui scegliere.

Nelle sezioni seguenti sono descritte le relazioni concettuali supportate nello schema DSPL.

Gerarchie

Le gerarchie di concetti sono rappresentate in DSPL tramite l'utilizzo di un attributo isParent="true" in un tag <property> del concetto secondario, che contiene gli identificatori delle istanze del concetto padre.

Ad esempio, il concetto di Google nella contea degli Stati Uniti ha il seguente formato:

<concept id="us_county" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">County</value>
    </name>
    ...
  </info>
  ...
  <property id="state" concept="us_state" isParent="true"/>
  ...
  <data>
    <table ref="reference_us_counties"/>
  </data>
</concept>

La tabella dei dati di supporto ha una colonna state con il codice di due lettere per ogni contea. Questo tipo di metadati consente a Public Data Explorer di mostrare stati e contee come gerarchia, una funzionalità che semplifica l'esplorazione agli utenti.

Tieni presente che un concetto può avere molti figli, ma non più di un genitore.

Mappature

Le mappature dei concetti (ovvero i concetti che rappresentano, sostanzialmente, la stessa cosa) sono rappresentati tramite un attributo isMapping="true" in un tag property del concetto mappato.

Se specifichi che un concept mappa a un altro, il primo eredita tutte le proprietà e gli attributi del secondo. Tra le altre, ciò è utile per "collegare" i concetti geografici personali con quelli definiti nel set di dati geografici canonico di Google:

<concept id="my_country" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">Country</value>
    </name>
    ...
  </info>
  ...
  <property id="google_country_code" concept="geo:country" isMapping="true"/>
  <data>
    <table ref="countries_concept"/>
  </data>
</concept>

Estensioni

Le estensioni concettuali vengono indicate tramite un elemento extends nella definizione corrispondente. Le estensioni sono utili per indicare che un determinato concetto è una sottoclasse di un altro concetto più ampio. Il concetto esteso eredita tutti gli attributi e le proprietà del relativo elemento principale e può anche aggiungerne altri.

Ad esempio, il concetto currency di Google estende unit:

<concept id="unit">
  ...
</concept>

<concept id="currency" extends="unit">
  <info>
    <name>
      <value xml:lang="en">Currency unit</value>
    </name>
    ...
  </info>
  ...
  <table ref="currency_table"/>
</concept>

Consulta la discussione sulle estensioni concetti nel tutorial per ulteriori spiegazioni ed esempi.

Inviare il set di dati

Per inviare il tuo set di dati a Google Public Data Explorer, segui queste istruzioni:

Creare una directory.
Salva il file dspl del set di dati nella directory che hai creato. Assicurati di utilizzare l'estensione .xml.
Salva tutti i file .csv locali nella stessa directory. I file di dati a cui viene fatto riferimento tramite gli URL possono essere omessi.
Comprimi la directory.
Carica il tuo set di dati in Google Public Data Explorer.

Dopo aver caricato e convalidato il set di dati, puoi testarlo quando accedi al tuo Account Google. Verrà pubblicata solo dopo che avrai controllato e comunicato che è pronta.